On Sat, Oct 7, 2017 at 7:12 PM, Robert Ramey via Boost
* Can I, starting with a blank sheet of paper, easily explain what this does?
I've lost track of the number of times I've redesigned something because it failed that test.
WOW - Great minds think alike!
I am also in agreement. I find that just as I am writing the declaration for a class or function, and I have a vision fixed in my mind of what the thing should do and its preconditions, postconditions, inputs, and outputs are, that it is the best time to write documentation. And what better place to put that documentation than in a specially formatted comment immediately preceding the function declaration? Here's an example from some code I am in the middle of writing: /** Return `true` if the known scheme is a special scheme The list of special schemes is as follows: ftp, file, gopher, http, https, ws, wss. @param s The known-scheme constant to check @return `true` if the scheme is special */ bool is_special(scheme s);
...tools that extract documentation direct from code have the effect of...explaining what their code actually does. ... 100% agree. I do agree that these tools might be helpful...
Yes, they are quite helpful because these tools can extract the type of comment I have shown above. Here's an actual example of the output of a tool which extracts specially formatted documentation comments that precede a function declaration: http://vinniefalco.github.io/nudb/nudb/ref/create.html Thanks