Overload pages shows the description and documentation for the first overload

[anarthal]

https://www.boost.org/doc/libs/master/doc/antora/url/reference/boost/urls/url/2constructor.html

I think this is confusing.

[alandefreitas]

We got that pattern from Boost.JSON, where the documentation comes from the first member. It works most of the time for member functions. But it's terrible for things like operator<<.

We can start by removing the description and only showing a union of the parameters, which is less controversial. Later, we could reintroduce a better way to inherit details about the overload set from the functions.

A number of heuristics could be used here:

• Don't inherit details from free functions
• Inherit details when only one overload is documented
• ...

[anarthal]

Do you mean from Docca? Actually, Docca will group overloaded functions by brief description, and never show details. See this example from Boost.JSON.

In any case, details usually differ from function to function, so I'd say it's unwise trying to show them in an overload page.

So I'd say to either replicate what Docca does, or simply drop all the text as you suggest.

[anarthal]

This is one of the issues that I'd like fixed before adopting MrDocs, since overload pages are very confusing right now. If I can help anyhow, let me know.

[anarthal]

As an idea for the future, Doxygen supports member groups - see the second part of the linked page. You can document a member group as an entity. Maybe MrDocs could support a similar syntax.

To be fair, in the ideal world, I'd prefer all information for an overload set to be documented in a single page. Something along the lines of what cppreference does. Of course, I don't think this is attainable right now.

[alandefreitas]

Do you mean from Docca?

No. I think it's from PyDocca.

details usually differ from function to function

It depends a lot. It's almost always awful for operators, but the details from the overload with the fewest parameters (typically the first one) are almost always appropriate to represent the overloads in member functions.

So I'd say to either replicate what Docca does, or simply drop all the text as you suggest.

Yes. Removing the details for now should work fine.

To be fair, in the ideal world, I'd prefer all information for an overload set to be documented in a single page

Yes. That's what cppreference does. We have to achieve that somehow. I think taking the details from the first overload tends to work fine if you keep that in mind, which is what I think Boost.JSON does. But that's not a good general solution. We need to find a way to put this together. But let's get rid of the details for now.

Doxygen supports member groups

Yes. We intend to support that. But that's an independent kind of feature. It doesn't solve the problem with overloads.

[anarthal]

Well, PyDocca attempts to replicate Docca's behavior. I use PyDocca in MySQL, and it does not use detailed descriptions in overload pages. For instance, see how boost::json::value::as_bool() has different brief and detailed descriptions (link), and how it's rendered: only brief descriptions are shown in the overload page, with functions being grouped by brief description (link). Replicating this behavior would work for me.

[alandefreitas]

@grisumbras what's the heuristic used in pydocca?

[grisumbras]

Here's the relevant code: https://github.com/boostorg/docca/blob/develop/include/docca/quickbook/components.jinja2#L300-L312

Essentially, it looks at the brief of each overload and if it differs from the previous one it outputs the brief before outputting the overload declaration.

Also, the overloads are sorted by their briefs (https://github.com/boostorg/docca/blob/develop/docca.py#L1052-L1067). This is a bit controversial, though.

[alandefreitas]

So we

1. Sort overloads by their briefs
2. Take the first brief

?

I think the original question is more about the details, though. Are they just discarded? Or does it do the same thing it does with briefs?

[anarthal]

No. groupby(brief), then, for each member in that group, print the brief, followed by the function declarations that share brief. Details are not output in overload pages.

See the example I posted earlier: https://www.boost.org/doc/libs/1_87_0/libs/json/doc/html/json/ref/boost__json__array/array.html

[alandefreitas]

Details are not output in overload pages.

OK. That's the part I wanted to know about. I thought it had a heuristic for copying the details under certain conditions. But looking at the page again, it doesn't make a union of the parameters, so trying to infer the details would be too much in comparison.

Grouping the members by briefs is more of a matter of presentation. A custom template could already achieve this in MrDocs.