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.
The reference documentation is the doxygen generated html/pdf/etc. It is
in many ways superior to headers+comments. The API is available online,
and we could also install it on make install, so that plugin authors are
not required to download anything.
Best regards.
_______________________________________________
Devel mailing list
Devel@lists.geany.org
https://lists.geany.org/cgi-bin/mailman/listinfo/devel
