I discovered that when linking to methods in external documentation (the URLs and anchors for which are documented in an XML tags file) confusion can arise in linking to the correct entity when they have the same name, even though they are of different kinds and contain different functions/methods.

For example, in Objective-C / Cocoa, the NSObject class adopts the NSObject protocol, and there is no conflict because there is a separate namespace for classes and protocols. However, attempting to link to a method in the NSObject protocol (an action which fails if the NSObject class is included in the tag file, but the NSObject protocol is not) doesn't produce an error, but incorrectly links to the NSObject class with the anchor for the protocol HTML page.

Note: The bug is further susceptible to ordering in the XML file. When the NSObject class is declared first, the protocol links mistakenly direct to the class page; if I reverse the order, the protocol links work correctly, but the links to the NSObject class direct to the protocol instead.

There is somewhat of a workaround, although it's annoying and incorrect: it requires renaming one of the entities in the XML and the links. For example, for some reason Doxygen names protocols with a trailing "-p". Doing the same in the XML and anywhere the protocol is linked works only partially; auto-links are deformed (the protocol name appears in plain text before the link, with no white-space in between. Using "_p" seems to work better. However, using "NSObject_p" instead of "NSObject" is esoteric and counter-intuitive, plus the inline comments become more confusing and somewhat less maintainable. (IMO, documenting code should be as natural as possible, requiring the fewest number of hoops to jump through as possible.)

It would be great if, when the link is created, the tool checks not only for a match of the containing entity, but also whether that particular entity contains the function/method/etc. specified in the documentation.