%[ER: 236]%

Document (in dutch) describing a number of ways that LOFAR package
documentation can be done within Doxygen.

.gitattributes

@@ -478,6 +478,7 @@ SDP/SPP/VHDL/FFT/aukfft_twidrom.tdf -text
 SDP/SPP/VHDL/FFT/aukfft_twidrom_4k.tdf -text
 autoconf_share/lofar_pvss.m4 -text svneol=native#application/octet-stream
 doc/UML/CPA-Packages-Model.mdl -text
+doc/doxygen/pkgdoc-howto.doc -text
 doc/doxygen/quick-guide.doc -text
 support/tools/BaseSimGUI/images/4.gif -text svneol=unset#unset
 support/tools/BaseSimGUI/images/5.gif -text svneol=unset#unset

doc/doxygen/pkgdoc-howto.cfg

+OUTPUT_DIRECTORY     = .
+OUTPUT_LANGUAGE      = dutch
+HTML_OUTPUT          = html
+INPUT                = pkgdoc-howto.doc
+GENERATE_LATEX       = NO

doc/doxygen/pkgdoc-howto.doc

+/**
+
+\page pkgdoc-howto LOFAR Package Documentatie: Hoe?
+\author Marcel Loose
+\date 26 januari 2005
+
+\anchor pkgdoc-toc
+<dl>
+<dt><b>Inhoud:</b></dt>
+<dd>
+  \ref pkgdoc-intro <br>
+  \ref pkgdoc-apart <br>
+  \ref pkgdoc-perpkg <br>
+  \ref pkgdoc-module <br>
+  \ref pkgdoc-conc <br>
+</dd>
+</dl>
+
+<hr>
+
+\section pkgdoc-intro Introductie
+
+Ik heb de afgelopen dagen uitgebreid onderzocht wat de beste methode is om de
+diverse LOFAR packages te documenteren en deze documentatie te integreren met
+de door Doxygen gegenereerde HTML pagina's. Er is een aantal manieren waarop
+integratie kan plaatsvinden. Ik zal er drie hieronder beschrijven.
+
+\ref pkgdoc-toc "[Inhoud]"
+<hr>
+
+\section pkgdoc-apart Aparte documentatie van packages
+
+Bij deze methode worden packages geheel onafhankelijk van de feitelijke source
+code documentatie beschreven. Doxygen biedt de mogelijkheid om dergelijke
+pagina's te maken m.b.v. structuurcommando's als \c \\page, \c \\section, \c
+\\subsection, etc. Het is ook mogelijk om referenties naar dergelijke pagina's
+en (sub)secties op te nemen.
+
+Helaas is het niet eenvoudig om een referentie naar de source-code
+documentatie van een package op te nemen. De belangrijkste reden hiervoor is
+dat het begrip \e package, zoals we dat binnen LOFAR kennen, niet
+&eacute;&eacute;n-op-&eacute;&eacute;n overeenkomt met de structuur in de
+source code; een LOFAR package is in feite een collectie van sources waarvan
+de object-code samengevoegd wordt in een software-bibliotheek. Hierdoor
+bestaat er geen `ingang' voor een package; er is geen HTML file waarnaar
+gelinkt zou kunnen worden.
+
+Doxygen kent weliswaar het begrip \e package, maar hiermee wordt dan een
+Java package bedoeld. De C++ `equivalent' hiervan is de \e namespace. Het
+moge duidelijk zijn dat de onderverdeling van LOFAR packages op dit moment in
+het geheel niet matcht met de gebruikte namespaces.
+
+
+<b>Voordelen</b>
+- De bestaande documentatie in de \c *.h files hoeft niet aangepast of
+  uitgebreid te worden. De beschrijving van packages is feitelijk gescheiden
+  van de beschrijving van de source code. (Dit is tevens een nadeel).
+
+<b>Nadelen</b>
+- De beschrijving van packages is teveel gescheiden van de beschrijving van de
+  bijbehorende source code. In feite is een `package' niets meer dan een
+  fysieke bundeling van de afzonderlijke object-files in een component (een
+  software bibliotheek).
+
+<b>Oplossingen</b>
+- De sources van ieder package zouden in een aparte namespace geplaatst moeten
+  worden. Hoewel dit een richtlijn is in de nieuwe, nog uit te brengen,
+  <em>C++ Coding Standard</em> is de praktijk anders. Toch is deze oplossing
+  niet volledig, omdat de nieuwe standaard voorschrijft dat ieder package in
+  de namespace \c LOFAR geplaatst moeten worden; packages worden dus niet
+  genest!
+
+\ref pkgdoc-toc "[Inhoud]"
+<hr>
+
+
+\section pkgdoc-perpkg Links naar `per package' Doxygen documentatie
+
+Bij deze methode ga je er vanuit dat ieder package afzonderlijk wordt
+ge-doxygen-d; dit is bijvoorbeeld het geval als je als ontwikkelaar een
+<tt>make doc</tt> doet in je eigen build directory. Je kunt Doxygen een
+zogenaamde <em>tag file</em> laten genereren. Je kunt vervolgens een globale
+LOFAR documentie pagina maken m.b.v. deze tag files. Feitelijk is deze methode
+bedoeld om de documentatie van third-party producten beter te kunnen
+integreren in je eigen documentatie.
+
+
+<b>Voordelen</b>
+- De bestaande documentatie in de <tt>*.h</tt> files hoeft niet aangepast te
+  worden.
+- Je kunt vanuit een willekeurige pagina eenvoudig linken naar een bepaald
+  package, omdat ieder package een eigen \c index.html en \c main.html file
+  heeft.
+- Alleen gewijzigde packages hoeven opnieuwe ge-doxygen-d te worden.
+
+<b>Nadelen</b>
+- De documentatie pagina's missen de benodigde samenhang. Ieder package
+  heeft namelijk zijn eigen `Main Page'. Je raakt hierdoor al snel het spoor
+  bijster.
+- In het algemeen is het navigeren lastiger, omdat je niet kunt linken
+  naar de `echte' hoofdpagina. Je kunt hier dan feitelijk alleen nog maar naar
+  terug m.b.v. de `Back' button.
+
+<b>Oplossingen</b>
+- Er is eigenlijk niet echt een oplossing voor het hierboven beschreven
+  probleem. De documentatie wordt namelijk in fragmenten gegenereerd. Het is
+  vervolgens erg lastig om hier weer een samenhangend geheel te maken.
+
+\ref pkgdoc-toc "[Inhoud]"
+<hr>
+
+
+\section pkgdoc-module Packages als Doxygen `modules'
+
+Bij deze methode wordt gebruik gemaakt van het \e Grouping mechanisme in
+Doxygen. Met behulp van \e Grouping is het mogelijk om een hi&euml;rachische
+\e view van zogenaamde \e modules op je project te cre&euml;eren. Hiervoor
+zijn de commando's \c \\defgroup, \c \\ingroup en \c \\addtogroup beschikbaar.
+
+
+\e Grouping is naar mijn idee &eacute;&eacute;n van de slechtst begrepen
+faciliteiten binnen Doxygen. De gebruikershandleiding is onduidelijk over \e
+hoe je `grouping' het beste kunt gebruiken. Een korte blik op <a
+href="http://www.stack.nl/~dimitri/doxygen/projects.html">voorbeeldprojecten</a>
+op de Doxygen site laat zien dat \e grouping op de meest uiteenlopende
+manieren wordt gebruikt.
+
+We zouden ervoor kunnen kiezen om de afzonderlijke LOFAR packages te
+documenteren in groepen. Omdat groepen genest kunnen worden, past dit goed
+op de hi&euml;rachische structuur van packages. 
+
+<b>Voordelen</b>
+- Het is eenvoudig om een hyperlink op te nemen naar de beschrijving van een
+  package, omdat Doxygen voor iedere \e module een aparte HTML file genereert.
+- Ook zogenaamde top-level packages, zoals CEP, kunnen worden gedocumenteerd.
+  Dit in tegenstelling tot de oplossing die genoemd wordt bij de
+  \ref pkgdoc-apart "eerste methode".
+
+<b>Nadelen</b>
+- De documentatie in alle bestaande <tt>*.h</tt> files moet worden aangepast.
+- Het is noodzakelijk dat er consci&euml;ntieus omgegaan wordt met het
+  toevoegen van de commando's \c \\defgroup, \c \\ingroup en \c
+  \\addtogroup. Helaas is dit nauwelijks te automatiseren en dus foutgevoelig.
+
+<b>Oplossingen</b>
+- Het is (deels) mogelijk om de software-ontwikkelaars te helpen door
+  zogenaamde sjablonen (\e templates) beschikbaar te stellen voor
+  bijv. <tt>*.h</tt> files, <tt>*.cc</tt> files, etc. Hierin zouden \e
+  placeholders opgenomen kunnen worden (bijv. \c $package$ en \c $class$) die
+  door een extern script automatisch juist ingevuld worden. Wellicht kan het
+  TMS project hierbij als voorbeeld dienen.
+
+\ref pkgdoc-toc "[Inhoud]"
+<hr>
+
+
+\section pkgdoc-conc Conclusies
+
+Als we de voor- en nadelen van de hierboven beschreven mogelijkheden bekijken
+dan kunnen we de voorzichtige conclusie trekken dat het wellicht het beste is
+(vanuit oogpunt van overzichtelijke documentatie) om te kiezen voor de laatst
+beschreven aanpak; om packages als \ref pkgdoc-module "Doxygen `modules'" te
+beschrijven. 
+
+Hoewel deze aanpak op de korte termijn nogal wat werk met zich meebrengt, werk
+dat \e niet eenvoudig met behulp van een script uitgevoerd kan worden, is dit
+mijns inziens wel de beste oplossing voor de lange termijn. We zullen nog wel
+moeten zoeken naar oplossingen om de juiste \e grouping commando's zoveel
+mogelijk automatisch te laten genereren, opdat fouten zoveel mogelijk worden
+voorkomen.
+
+\ref pkgdoc-toc "[Inhoud]"
+
+*/