Documentaie generat automat

Pentru documentarea codului scris, crearea manual a documentaiei este ineficient din mai
multe motive1. n general se folosete un generator pentru parsarea proiectului i extragerea
comentariilor introduse (n general folosind o sintaxa specific deasupra mecanismului standard de
implementare a comentariilor). Aceste informaii sunt apoi structurate ntr-o form sau alta (pe baza
unui 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 mai
multor limbaje de programare (Sandcastle C#, NaturalDoc, RoboDoc, etc.).
Un modul intern/integrat al unui IDE, aplicabil unui anume limbaj de programare (JavaDoc).

Java / Android
Observaii
Oracle pune la dispoziia programatorilor n Java un utilitar pentru generarea automat a
documentaiei (javadoc.exe2). Acesta permite parcurgerea automat a unui proiect Java i extragerea
comentariilor scrise n sintaxa acceptat (comentariile inserate ntre simbolurile /** */ 3). Fiind un
mecanism de documentare implementat la nivelul platformei el este integrat ntr-o suit ntreag de
IDE-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 de
asemenea editabil. Acest site poate fi postat online (inclusiv prin mecanisme automate de exemplu
dac la compilare output-ul este copiat ntr-o resurs online).
Sintaxa
Exist 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 lista
pop-down n cadrul seciunii /** */.
Exist de asemenea i un stil recomandat n mod oficial pentru scrierea comentariilor (vezi
linkul 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
2
3

Complexitatea procesului, posibilitatea modificrilor/coreciilor ulterioare, etc.

Situat n fiierul bin al platformei JDK instalate.
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

Utilizare
Dup 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 toate

fiierele s fie selectate, astfel nct s existe o bif albastr n seciunea Select types for wich
Javadoc 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:

Not
Exist i alte asemenea utilitare/aplicaii/plugin-uri care se pot utiliza pentru generarea
documentaiei automate (unele lucrnd chiar pe sintaxa JavaDoc).

C#
Observaii
Mediul 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 din
proiectul curent, unde comentariile precedate de simbolul /// 4 sunt procesate la momentul compilrii
proiectului iar tagurile XML corecte sintactic sunt agregate n fiierul XML rezultat.
Rezultatul final este un fiier XML care este interpretabil de ctre dezvoltator, dar pentru
construirea unei documentaii coerente i uor de utilizat trebuie s se foloseasc un utilitar extern. O
asemenea 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 unui
GUI se poate folosi Sandcastle Help File Builder (SHFB https://shfb.codeplex.com/); acesta include
i utilitarul Sandcastle. Un alt avantaj al SHFB este c integreaz n mediul VS o serie de unelte ce
ofer capabilitatea de a manipula direct fiierele de help ale proiectului.

Comentariile obinuite sunt prefixate de simbolul //.

page 4 of 10

Documentaie generat automat

Sintaxa
Exist 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
Utilizare
Dup 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 pot
instala i diverse unelte care s permit generarea i utilizarea mai facil a documentaiei
automate 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 mai
jos) 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/buildhtml-documentation-for-y.html .
Not
Exist 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