Re: Recommendations for documentation authors

From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2024-01-03 15:12:26

On Wed, Jan 3, 2024 at 12:01 AM Andrzej Krzemienski <akrzemi1_at_[hidden]>
wrote:

> I understand that it is work in progress as for now. I am not satisfied
> with the present result. Take `pct_encoded_rule_t` for instance. It is
> listed as "type", but it is actually an alias template whose *role* is to
> be a *meta-function*. Users need to know about it. This classification into
> namespaces/types/functions/enums/variables is insufficient for C++. For
> instance we use classes as *tags* (like std::in_place_t) and this is
> something different than using classes for maintaining an invariant.
> There are those cases from Boost.Beast when class X implements function
> X::f(), as required by the concept, but it does so via derivation. But we
> want to keep the fact of deriving as an implementation detail not exposed
> in the documentation.
>

Yes you are right about all of this, and I too desire better results.
However our initial goal is only to replace the use of Doxygen with Mr.
Docs in Boost.URL, not to innovate. At least, not yet. Once we have rid
ourselves of Doxygen, having better tools to allow us to express things
like metafunctions, traits, and concepts is *exactly* the reason why Mr.
Docs was started in the first place!

Krystian Stasiowski is our principal engineer on the project and he is very
knowledgeable with the C++ standard, and he's got big plans for Mr. Docs :)

We end up with the situation as in
>
> https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope/error_code_checker.html
> Where I need to click on type `result_type` only to learn on a separate
> page that it is `bool`.
>

Yes I agree with you. The default set of Mr. Docs templates are designed
only to recreate what is currently produced using docca. So as of now Mr.
Docs is going to emit reference documentation that looks just like what you
will find in Boost.Beast, Boost.JSON, Boost.URL, et. al.

The cool thing about Mr. Docs though is that these templates can be
customized. I know that many Boost authors prefer a different style where
the entire class declaration is repeated at the top of the page, and then
individual function signatures (and types) are listed below with
corresponding documentation. Like this:

https://www.boost.org/doc/libs/1_76_0/libs/system/doc/html/system.html#ref_boostsystemerror_code_hpp

Our future plans for Mr. Docs include the creation of additional template
sets to allow for this style of documentation. This is possible without
changing any of the C++ code or recompiling Mr. Docs. Of course, if someone
wants to start this work today we would be glad to provide assistance.

A final note, in terms of rendering metafunctions and that sort of thing we
will very likely require concepts as those work quite well. Even if the
library does not require C++20, with the use of #ifdef, Mr. Docs can
compile the program with C++20 enabled and then the concept declarations
will work:

    #ifdef MRDOCS_USE_CONCEPTS
        template<typename F>
            concept has_function_traits = requires {
                typename function_traits<F>::return_type;
                typename function_traits<F>::args_type;
            };
    #else
            template<class F>
        struct has_function_traits : std::false_type {};
        ...
    #endif

C++ Alliance is working with another team in parallel to bring clang/llvm
up in terms of features for supporting javadoc comments surrounding
concepts and requires clauses. And we are also working on improving the AST
representation for these constructs.

Thanks