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

[Lex Trotman]

On 30 May 2014 00:46, Matthew Brush <mbrush at 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