Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2017-10-08 02:58:53

AMDG

On 10/07/2017 08:41 PM, Vinnie Falco via Boost wrote:
> 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);
> 

I find this rather lacking.  Except for the list,
it's mostly an English restatement of the declaration.
Saying the same thing three times is not really more
useful than saying it once.
- What is a "known-scheme?"
- Why are these schemes special?
  What does it mean for a scheme to be special?
  why should I care whether it's special?

In Christ,
Steven Watanabe