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

Reply via email to