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

[Lex Trotman]

On 26 May 2014 09:50, Matthew Brush <mbrush at codebrainz.ca> wrote:
> 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?

They are intended to be "accessible" via the generated doxygen
documentation, its not necessary to read the source.

>
> 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.

Its neater to have them in the public .h file sure, but I suggest that
they are going to be less likely to be kept up to date that way.  Most
of the editing happens in the .c files (I don't even open the .h much
of the time) so the doxygen comments in headers become out of sight,
out of mind.


>
> Does anyone feel really strongly about this?

No, but if you do move them, leave a comment in the .c file on any API
visible function as a note that its in the API, and should not be
changed without changing the API docs and bumping the API/ABI.


Cheers
Lex


>
> Cheers,
> Matthew Brush
> _______________________________________________
> Devel mailing list
> Devel at lists.geany.org
> https://lists.geany.org/cgi-bin/mailman/listinfo/devel