KLauncher API documentation

[Adriaan de Groot]

On Sun, 18 Dec 2005, Kevin Krammer wrote:
> On Sunday 18 December 2005 18:12, Benjamin Meyer wrote:
>> On Sunday 18 December 2005 1:41 pm, Dominik Haumann wrote:
>>> On Sunday 18 December 2005 00:34, Frans Englich wrote:
>>>> IMHO, documentation is always valuable. Of course, in the case that the
>>>> documentation is read by vastly more readers(which it is, when part of
>>>> a public API), it is even more valuable.
>
> True, but the documentation in headers is still available when the respective
> -devel package is installed, source files are not.


You can put APIDOX in the header files -- in which case they're readable 
for everyone with -devel packages (or just regular packages for 
people on non-retarded distro's) and everyone with online access (that's 
what api.kde.org is for). You can put APIDOX in the C++ sources, in which 
case they're only readable online. You can also put APIDOX in *.dox files, 
where the same applies (and it takes some extra effort to add @class 
tags).

All three show up online. Only in header files are they always readable. 
Adding them to header files causes excessive recompilation (but only 
once).

Personally, I'd go for the following heuristic:

* Methods that may be used should be documented in the headers.
* Methods that shouldn't be used publically should be documented in the 
C++ source.
* Protected methods should be documented in the C++ source if the class 
isn't really meant to be subclassed.
* Lengthy examples in .dox files.

As for doxygen complaining about undocumented protected members: that's 
controlled by kdelibs' doc/api/Doxygen.local (something like that, 
anyway). You can change the complaints settings on a 
directory-by-directory basis (see the APIDOX howto on developer.kde.org). 
However, I think that protected members _should_ be documented just as 
much as regular members. After all, they're available to any subclass, so 
if you have library classes with protected members which are subclassable, 
then you have to see the protected members as 'almost public'.

[ade]