Re: [boost] Recommendations for documentation authors

śr., 3 sty 2024 o 16:12 Vinnie Falco napisał(a):

On Wed, Jan 3, 2024 at 12:01 AM Andrzej Krzemienski 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... 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_b...

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;