Documentaie generat automat

Pentru documentarea codului scris, crearea manual a documentaiei este ineficient din maimulte motive1. n general se folosete un generator pentru parsarea proiectului i extragereacomentariilor introduse (n general folosind o sintaxa specific deasupra mecanismului standard deimplementare a comentariilor). Aceste informaii sunt apoi structurate ntr-o form sau alta (pe bazaunui template) i prezentate ntr-o form accesibil utilizatorului (document editabil sau PDF, site web,document wiki, etc.).

Acest generator poate fi: O aplicaie de sine stttoare care realizeaz toate operaiunile necesare. De obicei acest tip de

aplicaie suport una sau mai multe sintaxe pentru preluarea informaiilor i se preteaz maimultor limbaje de programare (Sandcastle C#, NaturalDoc, RoboDoc, etc.).

Un modul intern/integrat al unui IDE, aplicabil unui anume limbaj de programare (JavaDoc).

Java / Android

ObservaiiOracle pune la dispoziia programatorilor n Java un utilitar pentru generarea automat a

documentaiei (javadoc.exe2). Acesta permite parcurgerea automat a unui proiect Java i extragereacomentariilor scrise n sintaxa acceptat (comentariile inserate ntre simbolurile /** */3). Fiind unmecanism de documentare implementat la nivelul platformei el este integrat ntr-o suit ntreag deIDE-uri (Eclipse, NetBeans, InteliJ, etc.).

Comentariile Javadoc sunt acceptate inclusiv n cadrul platformei Android.Rezultatul final este un site web generat local (n locaia specificat; implicit aceasta este

folderul doc din proiectul-surs curent), conform unui anumit template standard. Acest template este deasemenea editabil. Acest site poate fi postat online (inclusiv prin mecanisme automate de exempludac la compilare output-ul este copiat ntr-o resurs online).

SintaxaExist un set specific de instruciuni recunoscute de generatorul javadoc.exe. Dac mediul de

dezvoltare suport facilitatea de autocomplete (de exemplu Eclipse), acestea vor fi afiate ntr-o listapop-down n cadrul seciunii /** */.

Exist de asemenea i un stil recomandat n mod oficial pentru scrierea comentariilor (vezilinkul oficial).

Pentru mai multe detalii: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#examples

(linkul oficial) http://students.cs.byu.edu/~cs240ta/fall2012/tutorials/javadoctutorial.html http://en.wikipedia.org/wiki/Javadoc

1 Complexitatea procesului, posibilitatea modificrilor/coreciilor ulterioare, etc.2 Situat n fiierul bin al platformei JDK instalate.3 Atenie, nu este vorba de comentariul marcat de /* .. */, care este vzut ca un comentariu normal, ce nu va fi analizat de

javadoc.exe.

page 1 of 10

Documentaie generat automat

UtilizareDup scrierea comentariilor n sintaxa corect (vezi exemplul jCalculator) se poate trece la

generarea documentaiei automate. n Eclipse aceasta se poate face astfel: Se selecteaz opiunea corespunztoare:

Se seteaz corespunztor parametrii de generare a documentaiei (ideal, ar trebui ca toatefiierele s fie selectate, astfel nct s existe o bif albastr n seciunea Select types for wichJavadoc will be generated n loc de ptrat albastru):

page 2 of 10

Documentaie generat automat

Setri suplimentare:

Generarea documentaiei:

page 3 of 10

Documentaie generat automat

Rezultatul:

NotExist i alte asemenea utilitare/aplicaii/plugin-uri care se pot utiliza pentru generarea

documentaiei automate (unele lucrnd chiar pe sintaxa JavaDoc).

C#

ObservaiiMediul de dezvoltare Visual Studio (2010) pune la dispoziia programatorului o modalitate de a

crea i structura documentaia automat sub forma unor fiiere XML. Procesarea acesteia se face dinproiectul curent, unde comentariile precedate de simbolul ///4 sunt procesate la momentul compilriiproiectului iar tagurile XML corecte sintactic sunt agregate n fiierul XML rezultat.

Rezultatul final este un fiier XML care este interpretabil de ctre dezvoltator, dar pentruconstruirea unei documentaii coerente i uor de utilizat trebuie s se foloseasc un utilitar extern. Oasemenea aplicaie este pus la dispoziia dezvoltatorului tot de Microsoft (n mod gratuit) Sandcastle(http://sandcastle.codeplex.com/).

Sandcastle este o aplicaie ce nu beneficiaz de interfa grafic. Dac se dorete utilizarea unuiGUI se poate folosi Sandcastle Help File Builder (SHFB https://shfb.codeplex.com/); acesta includei utilitarul Sandcastle. Un alt avantaj al SHFB este c integreaz n mediul VS o serie de unelte ceofer capabilitatea de a manipula direct fiierele de help ale proiectului.

4 Comentariile obinuite sunt prefixate de simbolul //.

page 4 of 10

Documentaie generat automat

SintaxaExist un set specific de instruciuni recunoscute de compilatorul instalat de Visual Studio

(2010). Dac mediul de dezvoltare suport facilitatea de autocomplete (de exemplu Visual Studio),acestea vor fi afiate ntr-o lista pop-down n cadrul seciunii ///. De asemenea perechile de taguri(start/sfrit) vor fi generate automat.

Pentru mai multe detalii: http://msdn.microsoft.com/en-us/library/aa288481(v=vs.71).aspx (documentaia oficial) http://msdn.microsoft.com/en-us/library/5ast78ax(v=vs.71).aspx (taguri XML recomandate

pentru utilizare) http://msdn.microsoft.com/en-us/library/5fz4y783(v=vs.71).aspx (alternativ la comentariile ///) http://www.codeproject.com/Articles/3009/C-Documenting-and-Commenting http://msdn.microsoft.com/en-us/magazine/cc302121.aspx http://msdn.microsoft.com/en-us/library/vstudio/b2s063f7(v=vs.100).aspx http://msdn.microsoft.com/en-us/library/cc302121.aspx

UtilizareDup scrierea comentariilor n sintaxa corect (vezi exemplul sharpCalculator) se poate

trece la generarea documentaiei automate. n Visual Studio 2010 aceasta se poate face astfel: Se seteaz proiectul s genereze la compilare documentaia XML:

page 5 of 10

Documentaie generat automat

Se vizualizeaz fiierul XML rezultat:

Se instaleaz SHFB. n funcie de versiunea de IDE intit (i de platforma .NET dorit) se potinstala i diverse unelte care s permit generarea i utilizarea mai facil a documentaieiautomate direct din interfaa Visual Studio.

Se creeaz un nou proiect SHFB, ntr-o locatie selectat. Se seteaz tipul document dorit ca output:

page 6 of 10

Documentaie generat automat

Setarea titlului, a stilului, etc.:

Sumarul (descrierea) proiectului:

page 7 of 10

Documentaie generat automat

Cmpuri vizibile n documentaie:

Se ncarc fiierul/fiierele XML care vor constitui baza outputului:

page 8 of 10

Documentaie generat automat

Se pornete operaiunea de generare a documentaiei (butonul de toolbar vezi imaginea de maijos) i se ateapt finalizarea ei (dureaz ceva, aa c avei timp de o cafea ):

Rezultatul:

page 9 of 10

Documentaie generat automat

Un tutorial suplimentar pentru utilizarea Sandcastle: http://broadcast.oreilly.com/2010/09/build-html-documentation-for-y.html .

NotExist i alte asemenea utilitare/aplicaii/plugin-uri care se pot utiliza pentru generarea

documentaiei automate (unele lucrnd chiar pe sintaxa XML standard) de exemplu Vsdocman(http://www.helixoft.com/vsdocman/overview.html).

PHP

Observaii

Sintaxa

Utilizare

Not

page 10 of 10