Re: [scope] Mr. Docs rendered reference

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2023-12-04 16:49:21

On 12/4/23 17:08, Krystian Stasiowski via Boost wrote:
> Hi everyone,
> 
> 
> My name is Krystian, and I'm a Staff Engineer at The C++ Alliance. I’ve
> been working on Mr. Docs, a clang based C++ documentation generator
> intended to serve as an alternative to Doxygen. Although Mr. Docs is not
> yet ready for release, I noticed that there was an issue with rendering the
> exception specification of destructors due to a bug in Boostbook. Thus, I
> would like to present Mr. Docs as a potential future alternative, and have
> generated a multi-page reference for Boost.Scope to demonstrate its
> capabilities:
> https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope.html
> 
> The output was created using the built-in Asciidoc generator and converted
> to HTML with asciidoctor. Since the Asciidoc generator uses handlebars
> templates to format the output, customizing the rendered documentation is a
> matter of modifying the templates.
> 
> Unlike Doxygen, Mr. Docs operates directly on the clang AST. This means
> that support for new/obscure language features is only limited by the
> extent of clang’s conformance to the latest C++ standard.
> 
> Any feedback is greatly appreciated. 🙂

Thanks. Looks like the tool might become a good alternative to Doxygen
in the future, if it is configurable enough and integrates well with
QuickBook.

I have a few notes and complaints to the generated output:

1. In general, avoid wasting space on the sides of the content. Make the
output span the majority of the display width.

2.
https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope.html

I would prefer if there was a separation of components by headers
instead of alphabetical lists of types, functions, etc. Libraries are
typically built such that a given header typically contains a group of
components (i.e. types, functions, variables) that pertain to a given
functionality. This association is lost when the library contents are
presented as flat lists like on the page above.

Flat lists may be useful as a symbol index for quickly searching the
symbol you want *when you know what you want*. Such an index could be
useful as a secondary addition to the main reference that should be
presented per header.

Also, I don't think deduction guides need to be listed on that page.

3. In class descriptions such as this:

https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope/scope_exit-0a.html

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

3.2. The synopsis should be followed by the class Description, not by
functions.

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.

3.4. Member functions should show the complete function signatures, not
just names. 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.

3.6. Links to headers should probably lead to a documentation generated
for that header rather than GitHub.

3.7. Any links to GitHub should use permalinks rather than links to
branches.

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. For example, I don't want private stuff like types in
detail namespace to be present in the generated docs. I would also like
to hide SFINAE tricks. For example, this page:

https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope/scope_exit-0a/2constructor.html

should look more like this:

https://lastique.github.io/scope/libs/scope/doc/html/boost/scope/scope_exit.html#idm3803-bb

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

5. In function description such as this:

https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope/make_unique_resource_checked.html

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

5.2. I don't think there's a point to the Return Value section. The
return type should already be visible in the Synopsis.

5.3. Parameter descriptions are missing.

6. On this page:

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

as well as these:

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

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

7. I hope there is a way to export information from the reference
documentation in an XML or QuickBook format so that it is possible to
add links to specific classes and functions reference pages from the
main documentation in QuickBook. (Yes, QuickBook is a requirement from
me, plain AsciiDoc doesn't offer some very useful features for me to
consider it a format to write in.)