"see-below" aliases

[alandefreitas]

We need a solution for aliases that are documented as "see below". For instance,

template<class BufferSequence>
using prefix_type = decltype(
    tag_invoke(
        prefix_tag{},
        std::declval<BufferSequence const&>(),
        std::size_t{}));

would usually be documented as

template<class BufferSequence>
using prefix_type = __see_below__

The usual doxygen solution would be

#ifdef LIBRARY_DOCS
template<class BufferSequence>
using prefix_type = decltype(
    tag_invoke(
        prefix_tag{},
        std::declval<BufferSequence const&>(),
        std::size_t{}));
#else
template<class BufferSequence>
using prefix_type = __see_below__;
#endif;

but that doesn't work for us because MrDocs needs the code to be valid C++.

In principle, one could just define a detail::see_below symbol and use it. Then render it differently in the template.

Or also, something like:

#define __see_below__ void

[alandefreitas]

Some solutions:

1) MrDocs injects the symbols mrdocs::__see_below__ and mrdocs::__implementation_defined__. The user can use these symbols when parsing with MrDocs. 2) A command such as @mrdocs see_below is_charset or @mrdocs see_below (above charset) that makes the symbol be defined as __see_below__ in the documentation. 3) A filter, such as boost::urls::detail::* for symbols that should be considered "__see_below__" symbols.

[alandefreitas]

When implementing the issue, the documentation should explain why libraries need see_below and implementation_defined.

"see below" is a notational shorthand which may be used to direct the reader to exposition explaining in plain terms the meaning of the type, as an alternative to a cumbersome and lengthy SFINAE expression.

This is the "escape hatch" for when the actual type is too ugly or cumbersome to name. Even if the actual type is manageable, the author of the documentation may not want it to appear. Because they want to make it clear that the actual type is an implementation detail and subject to change

and also include examples.

Then show a table with a two column example of a type, on the right the actual type and on the left with "see below"