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

[Thomas Martitz]

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.

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.

Best regards.