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

[Matthew Brush]

On 14-05-29 08:01 AM, Lex Trotman wrote:
> 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.
>

Yeah, either way, I just meant since with the related changes we would 
need to put the G_MODULE_EXPORT on the public API functions anyway, we 
could do something like:

     #define GEANY_API_EXPORT G_MODULE_EXPORT

to provide the same meaning as the comment, provide the needed export, 
and also to minimize confusion between GtkBuilder exported callbacks and 
actual public API functions (same as a little comment would).

Cheers,
Matthew Brush