diff --git a/.gitattributes b/.gitattributes index bd5968ae3fb577bb335f1f99282f1e5ca6c5192a..87c21a4af2c84ed5b5964a6c744d08b254146859 100644 --- a/.gitattributes +++ b/.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 diff --git a/doc/doxygen/pkgdoc-howto.cfg b/doc/doxygen/pkgdoc-howto.cfg new file mode 100644 index 0000000000000000000000000000000000000000..1fc9daea3fac30fbcec57977dc95881bb4dd8f64 --- /dev/null +++ b/doc/doxygen/pkgdoc-howto.cfg @@ -0,0 +1,5 @@ +OUTPUT_DIRECTORY = . +OUTPUT_LANGUAGE = dutch +HTML_OUTPUT = html +INPUT = pkgdoc-howto.doc +GENERATE_LATEX = NO diff --git a/doc/doxygen/pkgdoc-howto.doc b/doc/doxygen/pkgdoc-howto.doc new file mode 100644 index 0000000000000000000000000000000000000000..30fcb1672d9076a8804432cf99384d5afc0116e0 --- /dev/null +++ b/doc/doxygen/pkgdoc-howto.doc @@ -0,0 +1,174 @@ +/** + +\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 +één-op-éé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ërachische +\e view van zogenaamde \e modules op je project te creëeren. Hiervoor +zijn de commando's \c \\defgroup, \c \\ingroup en \c \\addtogroup beschikbaar. + + +\e Grouping is naar mijn idee éé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ë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ë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]" + +*/