Boost.URL reference features

[alandefreitas]

This is a list of some features missing from the mrdocs reference when we compare

https://788.urlantora.prtest2.cppalliance.org/site/url/reference/index.html

and

https://www.boost.org/doc/libs/master/libs/url/doc/html/url/ref.html

• Template compile errors
  • Main template sections need names. xrefs get their default display names from the first level 1 section in the file. That's what makes xref:reference/index.adoc[] usually render as Reference or something like that but it renders as reference/index.adoc because the name comes from the first level 1 section in file and the templates start at level 2. One solution is to make the main section level 1. There's also a reftext attribute that can be set for the page but I think the first solution is not only easier but also better.
  • Broken xrefs. Pages contain xrefs such as xref:boost/urls/params_base.adoc that gives us lots of errors such as target of xref not found: ../../../../../boost/urls/grammar/range/iterator/reference.adoc. The problem is it assumes the reference will always be in the root of modules/ROOT/pages, which is almost never the case and would conflict with the exposition. Ideally, antora would support relatives paths for xrefs such as xref:../../params_base.adoc[params_base] and this would solve all cases. I don't think that's possible. The alternative is having an option to specify the prefix path for these xrefs. A temporary workaround is to have a hardcoded prefix such as reference: it's hardcoded and imposes an obligation on the user but makes it usable. (I fixed this manually in the preview above so we can compare the documentation)
  • Some other links are simply broken. target of xref not found: reference/std/__is_nothrow_constructible_impl.adoc file: C:\Users\aland\Documents\Code\C++\boost\libs\url\doc\modules\ROOT\pages\reference\std.adoc I suspect that has something to do with :relfileprefix: ../ but I never used this property before.
  • Some files such as std.adoc give me 788BE0EE2B9E1883DC13CA753557E782CA76A23C: Block ID pattern invalid, problem with prefix 788. Although I believe we will need to create some safe names for these sections anyway because referring to <<788BE0EE2B9E1883DC13CA753557E782CA76A23C, std>> from the exposition would be very inconvenient.
• Index:
  • The global namespace is not an unnamed namespace (see the introduction in https://en.cppreference.com/w/cpp/language/namespace)
  • The symbols presented in the index make very little as the symbols the user is interested when exploring a library. It has boost, std, and nothing else. This is usually a list of symbols of interest in the library. (See https://www.boost.org/doc/libs/master/libs/url/doc/html/url/ref.html) At the first level, we have to describe the main symbols of the library. At a second level, we have modules, which are URL, RFC, and grammar in this case. As a temporary solution, the symbols from these namespaces could be listed separately which would match the intended modules almost perfectly at least for Boost.URL. This is also valid for namespace pages, which should have the symbols categorized by their types (there's a handlebars helper for that).
  • Some symbols, such as empty_value.adoc are def'ed out in doxygen and are not supposed to be documented. Doxygen doesn't really compile the code, so things are simple there. We might need to come up with our own solutions for mrdox. It might be just a matter of filtering it. This is a little more complex for things like make_void.adoc, which is excluded but also in the url namespace. This one is in boost/url/detail/* and should have been excluded for this reason.
• Symbols: I think most problems with pages about symbols have already been discussed on slack... in any case
  • "Defined in file: " should use relative paths and always refer to the definition in the hpp file with the javadocs

Feel free to add to this list... :)

[alandefreitas]

https://792.urlantora.prtest2.cppalliance.org/site/url/reference/boost/urls.html

More items:

• mrdocs doesn't pick up the javadocs for many classes (https://792.urlantora.prtest2.cppalliance.org/site/url/reference/boost/urls/ignore_case.html). Probably because they have some ifdefs involved (https://github.com/boostorg/url/blob/cf2a888c42dedc25f8223dc61d4707e83bd7a22b/include/boost/url/ignore_case.hpp#L31-L37).
• Classes that are ifdeffed out are being documented: https://792.urlantora.prtest2.cppalliance.org/site/url/reference/boost/urls/ignore_case_t.html / https://github.com/boostorg/url/blob/cf2a888c42dedc25f8223dc61d4707e83bd7a22b/include/boost/url/ignore_case.hpp#L18-L22
• Index/namespace functions are including functions instead of function overloads
• Some functions are not being included in the reference. For instance, https://github.com/boostorg/url/blob/cf2a888c42dedc25f8223dc61d4707e83bd7a22b/include/boost/url/format.hpp#L92 / https://www.boost.org/doc/libs/1_83_0/libs/url/doc/html/url/ref/boost__urls__format.html. I would guess the reason is that format.hpp doesn't have a corresponding format.cpp file so it's not instantiated when we build Boost.URL without the tests (building with the tests ends up including a lot of junk in the documentation).
• mrdocs needs to fix the removal of the previous develop release before creating a new one. Not fixing this problem is creating draft releases and breaking the links Antora needs to download mrdocs. chore: version is 0.0.1 #507

[alandefreitas]

Some more:

• "Defined in header ..." needs links (feat: templates have access to config #505)
• Private base classes are being shown: https://mrdocs.com/demos/develop/boost-url/multi/adoc-asciidoc/boost/urls/authority_view.html
• unnamed enumerations have an invalid synopsis
• Aliases are documented with the alias itself on the right-hand side: using error_category = error_category; (now they are using error_category = system::error_category;, which is not relative to the current alias namespace as in https://www.boost.org/doc/libs/master/libs/url/doc/html/url/ref/boost__urls__error_category.html.

[alandefreitas]

Break down issues left into other issues with the Boost.URL milestone

[alandefreitas]

The remaining problems in this issue have been split into #582, #583, #584, #585, #586, #587