Re: Recommendations for documentation authors

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2024-01-03 16:40:53

śr., 3 sty 2024 o 16:12 Vinnie Falco <vinnie.falco_at_[hidden]> napisał(a):

> 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 for the update.
And about the Asciidoctor templates, does anyone use them to generate Boost
documentation with visuals similar to BoostDoc?

Regards,
&rzej;