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.
Sterling
