Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2017-10-08 02:41:28

On Sat, Oct 7, 2017 at 7:12 PM, Robert Ramey via Boost
<boost_at_[hidden]> 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...

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