Type aliases with template parameters are rendered wrong

[anarthal]

Example: https://www.boost.org/doc/libs/master/libs/mysql/doc/html/mysql/ref/boost__mysql__metadata_collection_view.html

metadata_collection_view is defined as a type alias for boost::span<const metadata>, where metadata is an object defined by MySQL. I'd expect the reference page to only show the type alias, but it's also listing the member functions for metadata.

A slightly less clean example: https://www.boost.org/doc/libs/1_81_0/libs/beast/doc/html/beast/ref/boost__beast__http__file_body.html Where the member functions section contains functions from the file class.

If no member functions are defined for the type in the span, everything works fine though: https://www.boost.org/doc/libs/master/libs/mysql/doc/html/mysql/ref/boost__mysql__blob_view.html

[evanlenz]

Hi @anarthal (and @vinniefalco), I can see how the member functions are being included. I will dig into this further, but because C++ isn't my area of expertise, I was wondering if you would like to help me figure out the correct behavior in the general case. I'm including the technical detail below for my own reference and also for you, only if you're interested in digging deeper so as to help me figure out what should and shouldn't be included in the page (again, in the general case). If not, no worries. I still have a next step I will take regardless (see last paragraph below). Either way, we'll get this fixed for you.

The code is including all the info from a referenced typedef class in the data for the page:

• via this rule in base-extract-xml-pages.xsl.

You can see the intermediate result of this in your build directory in this file: bin.v2/libs/mysql/doc/_reference-dir/xml-pages/boost__mysql__metadata_collection_view.xml

The next stage of processing finalized the content of the page, ignoring the undesired parts of that inclusion:

• via these rules in base-stage1.xsl.

(Line 483 is what causes the included class to be rendered by default, and the subsequent rules make the exceptions.)

You can see the results of that stage here: bin.v2/libs/mysql/doc/_reference-dir/stage1/results/boost__mysql__metadata_collection_view.xml

Apparently, it is not ignoring enough!

To try and divine my original intentions for doing this, with some effort, I tracked down the older git history which sadly didn't get copied over to the current project. Here are the two relevant commits where I added this code (almost four years ago!):

• "Added support for typedef tables (referenced classes)"
• "Categorize referenced classes to avoid rule collisions"

My next step will probably be to disable the abovementioned line 483 and see what breaks in the other projects that use docca. (I have some test scripts that I use and I will now add the mysql project to the list to help guard against future regressions in your project as well!)

[anarthal]

Hi @evanlenz, thanks for looking into it :) For the MySQL page, the correct behavior is as follows:

• boost::span<T> is a class defined by a library external to Boost.MySQL, so we don't have any info on this class.
• Although metadata is defined by MySQL, boost::span<metadata> is a container of metadata objects, so it does not inherit any member function, property or description from metadata.
• The description section on top is good, but the member function section should not appear. As an image is usually better than words, I've hand-drawn what should and should not be shown.
• In the general case, unless I'm missing something, the docs for class TemplateClass<T> should not pull anything from the type T.

I'm afraid I'm not familiar with docca (and XSL scares me), so I'm afraid I won't be very helpful with diagnosis.

Cheers, Ruben.