Boost logo

Boost :

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

Boost list run by bdawes at, gregod at, cpdaniel at, john at