Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Jonathan Müller (jonathanmueller.dev_at_[hidden])
Date: 2017-10-07 07:12:54

On 07.10.2017 05:12, Steven Watanabe via Boost wrote:
> AMDG
>
> On 10/06/2017 03:38 PM, Niall Douglas via Boost wrote:
>> and moreover one which finally can parse
>> the worst possible C++ metaprogramming without blinking because anything
>> clang can parse can be documented.
>    Just because the parser can handle it, doesn't mean that
> it's a good idea.  For example, in documentation, I always
> hide complex SFINAE, and instead provide an English description
> of the conditions.  In general, I find the more complex the
> metaprogramming is, the more tweaking is required to turn
> the doxygen output into something sane.  This is rarely because
> doxygen can't parse the code, but is rather because the raw
> definitions in the source are not very human-friendly.

standardese is designed to handle such things.

For example, if you have:

```
template <typename T, typename = std::enable_if_t<…>>
void foo(const T& obj);
```

You can write the following documentation comment:

```
/// \notes Thie function does not participate in overload resolution 
unless T is …
/// \param 1
/// \exlude
```

And standardese will completely hide the SFINAE part away.