Asciidoc: do we want breadcrumbs in parameters?

[anarthal]

Given a function:

any_connection(
    boost::asio::any_io_executor ex,
    any_connection_params params = {});

Where the parameter boost::asio::any_io_executor is not documented, the following is rendered:

This is, if a parameter is a qualified name, every part of it gets its own link. I'm not very keen on this, since when a user clicks on an entity, they likely want to navigate to that entity, and not to the list of members of the namespace where it's in. When the entity is not documented, it looks like a glitch. Is there a way to disable this behavior and only get a single link for the entity?

For reference, the behavior I'm describing is what the old Docca toolchain does. See this page in Boost.JSON:

[anarthal]

(Note that boost::system::error_code there is a single link, and not three links).

[alandefreitas]

(Note that boost::system::error_code there is a single link, and not three links).

Yes. That's the main issue here. We could link each part of the qualified symbol or the complete thing. We decided that linking the parts is more useful and correct.

[anarthal]

cppreference does as I suggest. For instance, see how std::thread::id in this page is also a single link, instead of a link to std::thread, then another link to id.

I honestly don't see myself wanting to access the reference page for namespace boost. It's debatable whether someone would want to access the reference for namespace mysql. If I end up building a quickref page (as this one in Boost.Url), I'd say the answer would be no.

I'd ask to reconsider this with the info I provided. If you have a strong opinion against it, I'd ask to have a config option to enable the behavior that PyDocca and cppreference implement. We can also translate the question to other Boost authors using docca and see what they think.

Thanks,
Ruben.

[alandefreitas]

This can already be fixed with templates, although dealing with templates just for that is a hassle. I remember we had a long discussion about it on Slack, and that's the design people preferred.

I don't have a strong opinion against it. It would be much easier to link the whole thing.

I understand cppreference or anything generated with tools based on doxygen would render it differently. I don't even need the examples. Doxygen doesn't provide enough information to render it differently.

[alandefreitas]

To be more precise, I'm OK with it as long as everyone is on board. I don't want to have to revert it in a few months.

[anarthal]

Note that cppreference is not related to Doxygen AFAIK. It's a bunch of MediaWiki templates, and everything is manual. See this page.

Also note that AFAIK PyDocca does give you this info - scope there is the entity's "parent". You can create links to it, so you can render links as breadcrumbs, too.

These are just data points. If there were people who expressed preference for the current behavior, asking them before making a change or making it configurable might be wise.

[alandefreitas]

Note that cppreference is not related to Doxygen AFAIK.

Yes. I understand that quite well. I worked on the doxygen tagfile for cppreference in the antora cpp-tagfile extension. But there's an algorithm to generate the tagfile from the pages. It does have some conventions.

If there were people who expressed preference for the current behavior, asking them before making a change or making it configurable might be wise.

Yes. We had a huge discussion on slack. IIRC, I also preferred the doxygen behavior at the time.