Treść książki
Przejdź do opcji czytnikaPrzejdź do nawigacjiPrzejdź do informacjiPrzejdź do stopki
RozszerzenieJavadoc
przezAsciiDoc
JamesElliott
ProgramiściJavaznająjużJavadoc.Ci,którzysąwtemaciejużoddłuższegoczasu,
pamiętają,jakabyłatoistotnazmiana,ponieważJavastałasiępierwszympopularnym
językiem,któryzintegrowałgeneratordokumentacjibezpośredniozkompilatorem
istandardowymzestawemnarzędzi.WynikającaztegoeksplozjadokumentacjiAPI
(nawetjeśliniezawszebyłaonaświetnalubdopracowana)przyniosłanamwszyst-
kimogromnekorzyści,atrendrozprzestrzeniłsięnawieleinnychjęzyków.Jak
donosiłJamesGosling,Javadocbyłpoczątkowokontrowersyjny,ponieważndobry
redaktordokumentacjitechnicznejmógłbyzrobićtoowielelepiej”-natomiast
istniejeznaczniewięcejAPIniżredaktorówdokumentacjitechnicznej,azaleta
posiadaniaczegośpowszechniedostępnegozostaładobrzesprawdzona.
CzasamijednakpotrzebujeszczegoświęcejniżtylkodokumentacjiAPI-znacz-
niewięcej,niżmożeszzmieścićnastronachopisupakietówiprojektów,któreofe-
rujeJavadoc.Skupionenakońcowymużytkownikuprzewodnikiiinstrukcje,teoria
iszczegółoweinformacjeoarchitekturze,wyjaśnieniadotyczącełączeniazesobą
wielukomponentów...żadneznichniepasujedoJavadoc.
Czegomożemyzatemużyć,abyzaspokoićtepotrzeby?Odpowiedzizmieniałysięna
przestrzeniczasu.Wlatach80.ubiegłegowiekuprzełomowym,wieloplatformowym
narzędziemdotworzeniadokumentówtechnicznych,wyposażonymwGUIbyłFra-
meMaker.DogenerowaniaatrakcyjnejdrukowanejdokumentacjiAPIzapomocą
FrameMakera,JavadoczawierałnawetMIFDoclet-zczegopozostałatylkoszcząt-
kowawersjadlasystemuWindows.DocBookXMLoferujepodobnemożliwości
związanezestrukturąiłączeniem,wrazzotwartąspecyfikacjąiwieloplatformowym
zestawemnarzędzi,alebezpośredniapracazjegosurowymformatemXMLjestnie-
praktyczna.Nadążaniezajegonarzędziamidoedycjistałosiękosztowneiuciążliwe,
anawettedobrespośródnichstałysiętoporneiutrudniałypisanie.
Jestempodekscytowany,gdyżznalazłemlepsząodpowiedź:AsciiDoc-oferującycałą
siłęDocBookawłatwymdonapisania(iodczytania)formacietekstowym,wktó-
rymrobienieprostychrzeczyjesttrywialne,awykonywaniezłożonychjestmożliwe.
RozszerzenieJavadocprzezAsciiDoc
5
