adoc: 'Introduced Symbols' links to a page that is never generated for a using-declaration of an overloaded function

[jll63]

(authored by Claude)

Summary

For a using-declaration that introduces an overloaded function, the generated
"Introduced Symbols" table can link to a page that is never generated. The href is
built as if the introduced symbol were a child of the using-declaration's own
page, so Antora reports target of xref not found.

Observed

MrDocs generates boost/openmethod/aliases/final_virtual_ptr.adoc for
namespace aliases { using boost::openmethod::final_virtual_ptr; }:

[#boost-openmethod-aliases-final_virtual_ptr]
= xref:boost.adoc[boost]::xref:boost/openmethod.adoc[openmethod]::xref:boost/openmethod/aliases.adoc[aliases]::final_virtual_ptr
:relfileprefix: ../../../
...
== Introduced Symbols

[cols="1,4"]
|===
| Name| Description
| xref:boost/openmethod/aliases/final_virtual_ptr/final_virtual_ptr.adoc[`final_virtual_ptr`]
| Create a `virtual_ptr` for an object of a known exact class.
|===

The target boost/openmethod/aliases/final_virtual_ptr/final_virtual_ptr.adoc is the
alias page's own path with /final_virtual_ptr.adoc appended. No such file, and no
boost/openmethod/aliases/final_virtual_ptr/ directory, is ever emitted.

The real pages for that function are boost/openmethod/final_virtual_ptr-*.adoc (15
of them, one per overload). The row's description text is taken from the correct
symbol — the default-registry overload's brief — so only the URL is wrong.

Antora then reports:

error: target of xref not found:
  ../../../boost/openmethod/aliases/final_virtual_ptr/final_virtual_ptr.adoc
  (modules/reference/pages/boost/openmethod/aliases/final_virtual_ptr.adoc)

Reproduction

Public repo, mrdocs --config=doc/mrdocs.yml --generator=adoc --multipage=true:

• Bad row: https://github.com/jll63/openmethod, branch feature/any, commit
  a735c45 → boost/openmethod/aliases/final_virtual_ptr.adoc contains the row above.
• Empty table: same repo, branch feature/mrdocs-macros, commit f77e3c8 →
  the same page's "Introduced Symbols" table has no rows at all.

The only difference between the two that touches this function is the number of
overloads: 3 generated overload pages on f77e3c8, 15 on a735c45 (the later commit
adds = delete overloads taking std::any / boost::any in separate headers that
include the one declaring the alias).

Of the 19 alias pages that repo generates, final_virtual_ptr is the only one with a
non-empty "Introduced Symbols" table — every other using-declaration produces an empty
table. So the two symptoms may share a cause: whatever resolves the introduced symbol
usually finds nothing, and in this one case finds the symbol but computes its URL
relative to the wrong parent.

I tried to minimize and could not reproduce with a small input. Three attempts, all
with a using lib::f; in a nested aliases namespace:

1. Overload set and the using in one header → one row, correct URL
   (xref:lib/f-0e.adoc).
2. using in core.hpp, extra = delete overloads in a later header that includes
   it → empty table.
3. Same as 2, with the deleted overloads taking a type outside include-symbols →
   empty table.

So the trigger seems to need something further from the real header than I could
isolate. Happy to dig further if you can suggest what to vary.

Version

MrDocs version 0.8.0+14a36c8132df
Built with LLVM 23.0.0git
Build SHA: 14a36c8132df16dd00e47930a1b8f6b1c2ac9698

Linux x86_64, --generator=adoc --multipage=true.

[jll63]

Further evidence that the trigger is the size of the overload set, not anything about the
using-declaration itself.

I worked around this downstream by hiding the twelve = delete overloads from extraction
(#ifndef __MRDOCS__), for unrelated reasons — they are a guard, not API, and crowded the
overload list. That took final_virtual_ptr from 15 generated overload pages back to 3, and
the symptom disappeared: the "Introduced Symbols" table on
boost/openmethod/aliases/final_virtual_ptr.adoc is empty again, and the Antora build is back
to zero errors.

Nothing about the using-declaration changed — it is still using boost::openmethod::final_virtual_ptr;
in the same namespace in the same header. Only the number of overloads visible to MrDocs did.

So across four data points:

overload pages	"Introduced Symbols"
3 (before the any headers)	empty
15 (with them)	one row, malformed URL
3 (with them, = delete overloads hidden)	empty
3 (minimal repro, all in one header)	one row, correct URL

The last row is repro attempt 1 from the original report, which produced a correct
xref:lib/f-0e.adoc. So a small overload set can produce a well-formed row; it seems to be the
larger set that pushes URL computation onto the wrong parent.

The two commits cited in the original report are unchanged and still reproduce it — the
workaround landed afterwards, on a later commit.