Issue 8794 - Add DDOC_ANCHOR macro for qualified anchor links

[ntrel]

http://d.puremagic.com/issues/show_bug.cgi?id=8794

Currently there is no way to generate qualified anchor links in DDoc output - i.e. <a name="MyClass.myMember"></a> rather than just myMember.

This pull request adds a new DDoc macro, DDOC_ANCHOR, which is expanded wherever a symbol declaration appears in the documentation. The qualified symbol name is passed as argument $1. This is in contrast to DDOC_PSYMBOL, which only passes the current identifier without any context, and does so wherever the symbol name occurs in the document output, including text descriptions.

[yebblies]

The ddoc tests will need to be updated.

[andralex]

As @yebblies said, after fixing those this diff LGTM.

[ntrel]

Thanks for the comments. I've just now got the ddoc tests up & running on my system, so I will commit the *.html changes in the next few days.

[jpf91]

We just want the identifier, not overloads like TemplateDeclaration::toChars.
We don't want the template parameter list and constraints.

How does this work for function overloads? Will all overloads get the same anchor? We have to decide whether this is OK or whether we want unique anchors for all symbols (which probably means we'd have to use the mangled names as anchors)

[ntrel]

@jpf91: All overloads get the same anchor. I quite like being able to easily guess the anchor name to use for links, which is harder to do when using the mangled name. I can see how using the mangled name neatly solves the overload problem though. If we merge this PR, we could still add the mangled name as argument $2 to the DDOC_ANCHOR macro. I expect even when using the mangled name for anchors, this pull's qualified name would still be useful as jump-to link text - maybe embedded somehow like <a name="__mangledname" id="qualified.name"></a>.

[ntrel]

After fixing some issues, I've now committed the ddoc test changes. Note that I've only run the ddoc tests, not all compilable tests as I've had some trouble with the test suite - but hopefully the ddoc tests are the only ones really needed here.

Unfortunately I have found that template symbols that are themselves members of a template get null for their Dsymbol::parent field, at least at the stage that ddoc sees them. I'm not sure if that needs fixing before merging this pull, as it means such templates won't get a qualified anchor, and they occur quite frequently in Phobos.