Re: [boost] Asciidoc, an alternative for documentation

On 10/7/17 7:41 PM, Vinnie Falco via Boost wrote:

On Sat, Oct 7, 2017 at 7:12 PM, Robert Ramey via Boost wrote:

...

...

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

Much as I hate to disagree with someone who's agreeing with me I might note that I don't recommend documenting functions beyond simple statement of what it does except in very special cases. That is I personally don't recommend a page in the documentation dedicated to a member function. I also make a big distinction between concepts (type requirements), types (classes/struct), functions, and metafunctions. Robert Ramey