On 30 May 2014 00:46, Matthew Brush mbrush@codebrainz.ca wrote:
On 14-05-29 05:56 AM, Nick Treleaven wrote:
On 26/05/2014 01:23, Lex Trotman wrote:
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.
Agree, that's an important reason. Another benefit is less rebuilding due to header file changes.
It's unclear if you're actually against $topic or just pointing out more reason for keeping the public API comments private.
FWIW, the first point will/would be somewhat offset by the fact that public functions could/would have G_MODULE_EXPORT (or we could make some macro like GEANY_API_EXPORT or such for readability) to remind that a public function is being edited and there's sure to be a comment to edit as well. What's more, it's actually not that hard to always in all cases open a single header file and check if you broke the public API/docs, compared to all the other stuff required to making changes.
It just needs a comment on the implementation of the API functions.
The need for an API specific macro is a separate technical thing, in this case the purpose is to provide information to those pesky livewares so a comment is fine. :)
Just define a snippet with the comment /* API function */ or similar and paste it just before cutting the doxygen comment for transplantation.
Cheers Lex