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

[Thomas Martitz]

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.

> 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.

Best regards