A reference to a class from one of its own members resolves to its constructor #1359

A reference to a class, written in the doc comment of one of its own members, resolves to the class's constructor instead of the class:

/// A widget.
struct Widget
{
    /// Construct an empty widget.
    Widget();

    /// Resize it. See @ref Widget.
    void resize(int n);
};

/// Use one. See @ref Widget.
void use(Widget& w);

In the output, the @ref Widget of resize links to the constructor (#Widget-2constructor), while the identical one of use links to the class (#Widget).

Why it happens

Lookup starts in the record of the documented member and searches its members first, falling back to the enclosing scope only when nothing matched. For a function or an overload set, a plain name matches by member.Name == component.Name (src/mrdocs/Corpus.cpp, in lookupImpl), and a constructor's name is the class's, so the constructor wins.

In C++ a constructor has no name that lookup finds: Widget inside Widget names the class, and the constructor is only reachable as Widget::Widget. So the general fix is that a constructor never matches a plain name. #1317 handles the same problem for an inheriting constructor (using Base::Base;) with a check specific to using-declarations; that rule would cover both cases.