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

[Matthew Brush]

On 14-05-29 04:37 PM, Lex Trotman wrote:
> [...]
>> Ok, not super technical, but more compelling than "I'm too lazy to open the
>> header file/update the documentation if it's not directly above one place I
>> edit (instead of the other place I most likely have to edit)" :)
>
> Different people have different workflows, some open everything, some
> only open the minimum.
>

Yeah, I guess I just see the public headers as "the official interface 
description" of the API, so it follows that (IMO) all relevant in-source 
documentation/comments that describe what's in the API headers should be 
available in them, instead of scattered into various places. If you have 
the headers, you can use/understand the interface kind of idea.

> Everything the plugin writer needs should be in the doxygen API docs.
> If its not fix that, don't make the plugin writer read the source.
>
> After looking at the discussions I have changed my mind and think the
> comments should *NOT* be moved to the header.
>

OK, so that's one +1 for only some of the doc-comments being in the 
public headers (structs, enums, etc.), some being in the 
private/not-installed source files (functions), and some being in 
separate private/non-installed, non-code files (signals), and then 
requiring the user to have an Internet connection, Doxygen, or a 
combination of the not-installed source files and the installed API 
headers to be able to access the docs (ie status quo).

Does anyone else feel strongly either way?

FWIW, I don't really feel super strongly, it's just an idea that I had 
to help make the public headers more useful for the only people they're 
intended for (ie. plugin developers), along with the other stuff I want 
to work on like not exposing private stuff, ensuring all public stuff is 
properly documented, etc. None if this other stuff really hinges on 
moving the comments to the headers, it's just a parallel idea.

Cheers,
Matthew Brush