tl;dr: Propose that a prefixed hash (like #classname) express an explicit link without also changing the context to global scope.
Details: The automatic link generation documentation describes how to reference documented entities based on their type; e.g. for a function foo one may use any of seven options including foo(). Words that are not entirely lower case and that match a class name are automatically linked unless prefixed by percent (%notaclass). In the C++ style I'm using class names are all lower case. Some of these appear in namespaces. The bare forms of these names aren't recognized, and so links are not created. Historically I've worked around this outside namespace using #classname, interpreting the hash as a general indication of "make this a link reference" (I've used this in C code to reference defines, for example, and it's sanctioned in the automatic link generation documentation for similar uses). However, this approach doesn't work when the link target is inside the current namespace. The only solution I've found is to explicitly specify the full namespace in each reference in the documentation, which is verbose and tedious. It turns out that when src/docparser:handleLinkedWord() invokes resolveRef() the latter function unconditionally substitutes :: for # when forming the name that is resolved. The change I propose is that it do this only for hash marks that appear internal to the name, and that it instead strip a leading hash mark from the name for the purposes of locating the reference. (Due to the way the code is structured, the hash mark remains present when checking for all-lower case tokens, so the link is generated using the appropriate context.) I've submitted a pull request with the necessary patch as: https://github.com/doxygen/doxygen/pull/97 (I'd be happy to put all this into a bug report, but I can't find where those go now. The SourceForge bug database appears to have disappeared with the project update, and github tickets aren't enabled.) Below is the test input used to validate the change. Peter /** @file * * Reference no-hash tclass, hash #tclass, ns::nstclass, ns::NSTClass */ /** The class without namespace */ class tclass { public: /** The member in #tclass * * Reference no-hash tclass, hash #tclass, ns::nstclass, ns::NSTClass */ int member; }; /** The capitalized class without namespace * * Reference no-hash tclass, hash #tclass, ns::nstclass, ns::NSTClass */ class TClass { public: /** The parameter in TClass * * Reference no-hash tclass, hash #tclass, ns::nstclass, ns::NSTClass */ int member; }; /** A global function * * Reference no-hash tclass, hash #tclass, ns::nstclass, ns::NSTClass */ void ignoreme (); /** The namespace */ namespace ns { /** An override tclass in namespace * Reference no-hash tclass, hash #tclass, unqualified nstclass (hashed #nstclass) and NSTClass, qualified ns::nstclass, ns::NSTClass */ class tclass { }; /** The namespaced class * * Reference no-hash tclass, hash #tclass, unqualified nstclass (hashed #nstclass) and NSTClass, qualified ns::nstclass, ns::NSTClass */ class nstclass { public: /** The member in #nstclass * * Reference no-hash tclass, hash #tclass, unqualified nstclass (hashed #nstclass) and NSTClass, qualified ns::nstclass, ns::NSTClass */ int member; }; /** The namespaced capitalized class * * Reference no-hash tclass, hash #tclass, unqualified nstclass (hashed #nstclass) and NSTClass, qualified ns::nstclass, ns::NSTClass */ class NSTClass { public: /** The member in NSTClass * * Reference no-hash tclass, hash #tclass, unqualified nstclass (hashed #nstclass) and NSTClass, qualified ns::nstclass, ns::NSTClass */ int member; }; /** A namespace function. * * Reference no-hash tclass, hash #tclass, unqualified nstclass (hashed #nstclass) and NSTClass, qualified ns::nstclass, ns::NSTClass */ void nsignoreme (); } // ns ------------------------------------------------------------------------------ CenturyLink Cloud: The Leader in Enterprise Cloud Services. Learn Why More Businesses Are Choosing CenturyLink Cloud For Critical Workloads, Development Environments & Everything In Between. Get a Quote or Start a Free Trial Today. http://pubads.g.doubleclick.net/gampad/clk?id=119420431&iu=/4140/ostg.clktrk _______________________________________________ Doxygen-users mailing list Doxygen-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/doxygen-users
