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

[Nick Treleaven]

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.