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
_______________________________________________
Devel mailing list
Devel@lists.geany.org
https://lists.geany.org/cgi-bin/mailman/listinfo/devel
