On Mon, Jul 11, 2016 at 01:00:24PM -0700, Sterling Hughes wrote: > Hey, > > On 11 Jul 2016, at 12:45, Christopher Collins wrote: > > > On Mon, Jul 11, 2016 at 11:01:45AM -0700, Sterling Hughes wrote: > >> As Will points out, I’m OK if APIs are documented outside of the > >> code > >> itself. For the OS, I went through and added a bunch of Doxygen > >> comments, but the function calls and their variants were fairly > >> simple. Function calls that take big enums as a parameter can be > >> very > >> lengthy to document with doxygen, and I hate having them in the code > >> itself. > > > > I'm not sure how to read this. Are you saying API specifications > > comments are a liability? > > > > I am saying that I dislike excessively doxygen’d source code. It’s > fine to have a quick function spec at the top, but I’ve seen cases > where doxygen comments can span a full screen or more, for a single > function. The example given was a function that takes an enum with a > lot of values, where every value would be documented in the doxygen > comments. > > I’d prefer the API documentation outside of the source code in those > cases, as it inhibits readability of the actual source. In general, > I’m fine with Doxygen comments, but I don’t find them particularly > useful — give me a simple API and sample code anyday - I can figure > out the rest.
I think we've been discussing slightly different things. Here's my take, not intended to challenge what you've said (which I almost completely agree with). * Learning materials (e.g., tutorials and example applications) serve a different purpose from reference documentation. * Without a team dedicated to maintaining the reference documentation, it will always be out of date. * The people who actually work on the code are the most knowledgable about the specifics of individual functions and data structures - the things that are described in the reference documentation. * The developers look at their code much more often than they look at the web site. * Doxygen comments are in the same files as the code they describe, so they can be verified when pull requests are reviewed. Trying to keep the documentation on the web site up to date independent of the source code is hopeless. If the documentation is generated from doxygen comments, at least there's a possibility of it being mostly correct. I don't think I would be bothered by a full page of doxygen comments, but I accept that others may be. Chris
