|
Boost : |
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
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk