Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-10-08 04:46:02

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

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