[Geany-Devel] [RFC]: Public API comments in headers

[Matthew Brush]

On 14-05-29 11:58 AM, Thomas Martitz wrote:
> Am 26.05.2014 01:50, schrieb Matthew Brush:
>> Hi,
>>
>> As part of working on cleaning up the exposed API to plugins I got to
>> thinking about where our comments are located. While it's nice to keep
>> the API-documentation-comments right at the definitions of the
>> functions in their respective .c source files, since we only install
>> the headers as a public reference (not even the plugin API docs IIUC),
>> should we not move the API-documentation-comments, that we already
>> diligently ensure exist and are fairly complete, into the headers
>> where they are accessible to plugin developers?
>>
>> If we moved to having public headers that just included actual public
>> symbols, I think it would be advantageous to have those headers
>> totally commented/documented rather than requiring the user to
>> download Geany's source code and cross-reference functions in it to
>> access the comments/docs, or getting hold of the generated Doxygen API
>> documentation.
>>
>> Does anyone feel really strongly about this?
>
> Hello,
>
> I can't say I feel overly strong but my experience is that when
> implementation and comments are split that they begin to drift apart
> sooner or later. I suggest keeping things as they are unless there is a
> compelling technical advantage. We do a half decent job at documentation
> (which is better than 90% of other FOSS projects) and we should not risk
> that.
>

I agree somewhat, but it's actually not very hard to open the related 
header and check when changing the code, especially since often changing 
the API documentation means adding a new function, or changing the 
semantics/signatures of a function, or adding/changing a structure/type, 
which all requires editing the header anyway, so it's actually not 
really much extra work.

As far as technical advantage, it causes less misleading comments in the 
source (eg. documenting `@file foo.h` in the foo.c source file), avoids 
users having to get a copy of the Doxygen docs for the correct version, 
and finally to keep all the public API comments in the same public 
header file, instead of the current way where types (structs, typedefs, 
etc.) are necessarily documented in the header, but functions are 
documented in the internal non-installed source files.

> The reference documentation is the doxygen generated html/pdf/etc. It is
> in many ways superior to headers+comments. The API is available online,
> and we could also install it on make install, so that plugin authors are
> not required to download anything.
>

Not everything is actually documented in Doxygen though, so one often 
needs to reference the headers anyway, plus the online docs are for the 
latest release and not the development version of Geany (AFAIK), and 
additionally, installing the docs on make install (unconditionally) 
would mean we require the user to have at least Doxygen (plus Qt and all 
the stuff it requires) installed. But I agree we should (also) make the 
API docs installable and maybe for packagers to make them part of the 
-dev package for Geany if they wanted to.

Cheers,
Matthew Brush