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.