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

[Colomban Wendling]

Le 29/05/2014 21:43, Matthew Brush a écrit :
> [...]
>>>
>>
>> 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.
> 
>>> [...]
>>
> 
> 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)" :)

It's highly unlikely to edit the declaration, but likely to change the
implementation.  If you change the signature, you break the API, but if
you simply change the implementation you may add a further notice on a
limitation or a feature, or note that the function now accepts more
inputs or something.  I mean, touching that API happens 100% of the time
in the implementation side, while only <100% on the declaration side.
Also, I think 99% of the API docs edits don't follow an API breakage
(e.g. not touching the declaration).

And I agree with Thomas that moving it farther from implementation will
lower the probability of updating (just because you don't see the docs
and notice it's not good enough).


About where they should be, I'm used to placing them above the
*declaration*, no matter where it is.  And the above reason applies.


Apart that, I have not much to add to initial comments from Lex and
Thomas.  I don't feel strongly about this, but I don't think it has much
advantages (realistically I think all developers will look at the
generated docs anyway[1]), while I'm afraid it may have pitfalls.


My 2¢,
Colomban


[1]  Note that GLib and GTK don't have docs in the headers, so most
people will have to look at those docs from time to time anyway.