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

[Matthew Brush]

On 14-05-29 12:33 PM, Thomas Martitz wrote:
> Am 29.05.2014 21:21, schrieb Matthew Brush:
>> On 14-05-29 11:58 AM, Thomas Martitz wrote:
>>> Am 26.05.2014 01:50, schrieb Matthew Brush:
>>>> Hi,
>>>>
>>>> As part of working on cleaning up the exposed API to plugins I got to
>>>> thinking about where our comments are located. While it's nice to keep
>>>> the API-documentation-comments right at the definitions of the
>>>> functions in their respective .c source files, since we only install
>>>> the headers as a public reference (not even the plugin API docs IIUC),
>>>> should we not move the API-documentation-comments, that we already
>>>> diligently ensure exist and are fairly complete, into the headers
>>>> where they are accessible to plugin developers?
>>>>
>>>> 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.
>>>>
>>>> Does anyone feel really strongly about this?
>>>
>>> Hello,
>>>
>>> I can't say I feel overly strong but my experience is that when
>>> implementation and comments are split that they begin to drift apart
>>> sooner or later. I suggest keeping things as they are unless there is a
>>> compelling technical advantage. We do a half decent job at documentation
>>> (which is better than 90% of other FOSS projects) and we should not risk
>>> that.
>>>
>>
>> I agree somewhat, but it's actually not very hard to open the related
>> header and check when changing the code, especially since often
>> changing the API documentation means adding a new function, or
>> changing the semantics/signatures of a function, or adding/changing a
>> structure/type, which all requires editing the header anyway, so it's
>> actually not really much extra work.
>>
>
> It's not hard but it'll be still be forgotten/missed. We're just human
> beings.
>

But if you can forget it when you're editing the function/type 
declaration, why can't you forget it when you're editing the function 
definition? I just mean, either way, you need to look at the 
function/type and either update the comment or not, regardless where 
it's placed. Plus having a little comment or macro that hints that the 
function is public as discussed in the other messages would provide a 
bit of backup for people who aren't very conscious about whether they're 
editing public API or keeping the docs in sync.

>> As far as technical advantage, it causes less misleading comments in
>> the source (eg. documenting `@file foo.h` in the foo.c source file),
>> avoids users having to get a copy of the Doxygen docs for the correct
>> version, and finally to keep all the public API comments in the same
>> public header file, instead of the current way where types (structs,
>> typedefs, etc.) are necessarily documented in the header, but
>> functions are documented in the internal non-installed source files.
>>
>
>
> Neither of those are technical or (IMO) compelling.
>

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)" :)

Cheers,
Matthew Brush