Re: [scope] Mr. Docs rendered reference

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2023-12-05 14:32:14

On 12/5/23 16:48, Krystian Stasiowski via Boost wrote:
>> Also, I don't think deduction guides need to be listed on that page.
> 
> The plan is for deduction guides and template specializations to be
> associated with the primary template and enumerated on its corresponding
> documentation page.

I think, there's not much value in listing deduction guides anywhere at all.

Also, if you're going to show the deduction guides, then please show
them in full, instead of just the resulting type.

>> 3.4. Member functions should show the complete function signatures, not
>> just names.
> 
> Only the names are shown because overloads are grouped together and have
> their signatures displayed on a separate page. This keeps the list of
> members compact. Regardless, wouldn't this be made redundant by showing the
> full class definition in the synopsis?

Different function overloads should be presented separately. Their
documentation often differ, too.

Function signature should be near the function description so that the
user can see its parameters and return type, which are described in the
function documentation. Having to seek between the synopsis and function
description is a terrible user experience.

>> Also, it should probably separate constructors, destructor,
>> assignment operrators, other operators and regular member functions. A
>> simple alphabetical list doesn't make sense.
>>
>> 3.5. The list of functions should not contain deleted functions. If the
>> synopsis already shows them as deleted, there's no need to show them
>> separately in the function list without any description. In the linked
>> page, this pertains to the "operator=" and "scope_exit" entries.
>>
> It is impossible to have built-in support for every grouping and ordering
> of member functions a user may desire. The handlebars templates that ship
> with Mr. Docs will support a few variations, but it's ultimately up to the
> user to customize them to their liking.

It doesn't need to be customizable, a fixed grouping like the one I
described would be enough.

Re. deleted functions, that's not about grouping at all.

> 4. I hope, there is a way to detect Mr. Docs in code by testing a
>> predefined macro. This is useful in order to cleaning up the code for
>> documentation.
> 
> You can define macros in the config file. That being said, the resulting
> code should still be (mostly) valid, otherwise clang will not create AST
> nodes in more extreme cases.

I think the documentation tool should be more tolerant to code validity
than a plain compiler. Hiding stuff from documentation for readability,
where the resulting code is not a conforming C++ is common practice;
even the C++ standard does this.

> For example, I don't want private stuff like types in
>> detail namespace to be present in the generated docs.
> 
> The config allows for declarations whose qualified name matches a pattern
> (e.g. "boost::*::detail") to be blacklisted. By default, these filters are
> ignored when the "interface" of a documented declaration depends on another
> (e.g. class A : public detail::B), but this behavior can be disabled.

Such filters don't always work. For example, here:

https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope/unique_resource-0c/swap.html

you can see the type `data` is used in the documentation. This is a
private type (i.e. it is defined in a private section of the
unique_resource class) that should not be present in the docs.

>> I would also like to hide SFINAE tricks.
> 
> In the future we plan to detect the enable_if idiom (and others) and
> convert them to equivalent constraints, but this is way down the road. For
> now, macros will have to suffice.

I don't think auto-detection is needed. Just make it easy to hide stuff
from docs and make the tool more tolerant to non-conforming C++, that
would be enough, IMHO.