pkgdoc-howto.dox

/**

\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]"

*/