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

[Matthew Brush]

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.

The extra rebuilding would be offset by having the private and public 
stuff split into separate files, some files wouldn't even need to 
include the public headers anymore and so wouldn't trigger rebuilding as 
many files. In addition, if we were really worried about build 
times/include dependencies, we could use forward declaration in quite a 
few headers that just use an opaque pointer to a public type instead of 
including the whole header. I think overall we could actually reduce the 
amount of re-building required in addition to making the API comments 
accessible to the public API users who they're meant for.

Cheers,
Matthew Brush