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

[Matthew Brush]

On 14-05-25 05:23 PM, Lex Trotman wrote:
> On 26 May 2014 09:50, Matthew Brush <mbrush at codebrainz.ca> wrote:
>> [snip]
>>
>> 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.
>

If, in future changes, we used the `G_MODULE_EXPORT` stuff, and kept it 
at the site of the definition (in the C file), it might provide a queue 
for anyone changing it that it has related boilerplate, being an 
exported/public function. It might help a bit here at least.

Cheers,
Matthew Brush