On 14-05-29 04:37 PM, Lex Trotman wrote:
[...]
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)" :)
Different people have different workflows, some open everything, some
only open the minimum.
Yeah, I guess I just see the public headers as "the official interface
description" of the API, so it follows that (IMO) all relevant in-source
documentation/comments that describe what's in the API headers should be
available in them, instead of scattered into various places. If you have
the headers, you can use/understand the interface kind of idea.
Everything the plugin writer needs should be in the doxygen API docs.
If its not fix that, don't make the plugin writer read the source.
After looking at the discussions I have changed my mind and think the
comments should *NOT* be moved to the header.
OK, so that's one +1 for only some of the doc-comments being in the
public headers (structs, enums, etc.), some being in the
private/not-installed source files (functions), and some being in
separate private/non-installed, non-code files (signals), and then
requiring the user to have an Internet connection, Doxygen, or a
combination of the not-installed source files and the installed API
headers to be able to access the docs (ie status quo).
Does anyone else feel strongly either way?
FWIW, I don't really feel super strongly, it's just an idea that I had
to help make the public headers more useful for the only people they're
intended for (ie. plugin developers), along with the other stuff I want
to work on like not exposing private stuff, ensuring all public stuff is
properly documented, etc. None if this other stuff really hinges on
moving the comments to the headers, it's just a parallel idea.
Cheers,
Matthew Brush
_______________________________________________
Devel mailing list
Devel@lists.geany.org
https://lists.geany.org/cgi-bin/mailman/listinfo/devel
