Re: [scope] Mr. Docs rendered reference

From: Krystian Stasiowski (sdkrystian_at_[hidden])
Date: 2023-12-05 13:48:05

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

3.1. The Synopsis should show the class definition, with all its public
> members.

This is a planned feature and should be present upon release.

> 3.3. In the description of this class, the description seems to be
> incorrectly parsed. The list ends after the end of the first sentence of
> the last entry. "The condition function object operator() must..."
> should be displayed as a new paragraph after the list, not as part of
> the last entry of the list.
>
Thank you for pointing this out, I will address it.

> 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?

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

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.

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.

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

> Also, all of the documentation for the constructors seems to be missing.
>

> swap functions appear undocumented, but they are in the source code.
>

This is a clang bug. I will be submitting a patch to address this.

> 5.1. In the Description, part of the description (the "Throws:" part)
> seems to have been incorrectly merged with the Note.
>

> 5.3. Parameter descriptions are missing.
>
I'll address these issues, thanks :)