D-Programming-Language/dmd — pull request #865 by asterite (2012-04-04 05:35:18+00:00)
Title: Cross-references in generated ddoc

In this pull request there are two commits.

The first commit does three things:
* It changes the DDOC_DECL macro to also emit an html anchor () with the fully qualified name of the declaration, excluding the module name. So a class Foo::Bar inside some module would get an nchor equals to "Foo.Bar".
* Then when generating ddoc, instead of outputting a declaration's identifier, a link to that declaration is made with the LINK2 macro.
* Since aliases are resolved to their types and thus they wouldn't appear correctly in ddoc, I added an "originalSymboll" member to TypeIdentifier, that is the symbol the identifier resolved to. If it's available in ddoc, it is used. This works for plain aliases, but won't work for, for example, pointers to aliases or arrays of aliases (but I think that isn't a big deal).

Since D templates aren't semantically resolved until instantiation, the first commit can't generate cross-references for templates.

The second commit fixes that. What it basically does is search the idenfitier in the module's scope. This is almost always (if not always) the correct referenced type.

The only problem I found with my changes is this. In std.path there's a function like this:

```d
enum CaseSensitive { ... }

void baseName(CaseSensitive cs)(SomeType path) {}
```

CaseSensitive docs is located in the path.html. So the generate ddoc will have ```$(LINK2 path.html#CaseSensitive, CaseSensitive)```. But since highlightCode is invoked on that generated string, it becomes ```$(LINK2 $DDOC_PARAM(path).html#CaseSensitive, CaseSensitive)``` and after macros are replaced it will look like ```CaseSensitive````, which doesn't work.

So this only happens if a type is located in a module, and there's a parameter with that module name. If somebody knows a way to fix it (obviously not invoking highlightCode in this case could be a solution, but it won't be consistent with everything else), please let me know.

Actually, there's another problem. If you generate the ddoc with the -op then it won't work well. I still can't figure out how to deal with it if the directory structure is preserved. Again, if somebody has a solution for this, let me know.

I run this against phobos and it went just fine. You can see the output here:

http://pancake.io/1e79d0/algorithm.html
http://pancake.io/1e79d0/array.html
http://pancake.io/1e79d0/ascii.html
http://pancake.io/1e79d0/base64.html
http://pancake.io/1e79d0/bigint.html
http://pancake.io/1e79d0/biguintcore.html
http://pancake.io/1e79d0/biguintnoasm.html
http://pancake.io/1e79d0/biguintx86.html
http://pancake.io/1e79d0/bind.html
http://pancake.io/1e79d0/bitmanip.html
http://pancake.io/1e79d0/compiler.html
http://pancake.io/1e79d0/complex.html
http://pancake.io/1e79d0/concurrency.html
http://pancake.io/1e79d0/container.html
http://pancake.io/1e79d0/contracts.html
http://pancake.io/1e79d0/conv.html
http://pancake.io/1e79d0/cpuid.html
http://pancake.io/1e79d0/crc32.html
http://pancake.io/1e79d0/cstream.html
http://pancake.io/1e79d0/csv.html
http://pancake.io/1e79d0/ctype.html
http://pancake.io/1e79d0/curl.html
http://pancake.io/1e79d0/datetime.html
http://pancake.io/1e79d0/demangle.html
http://pancake.io/1e79d0/encoding.html
http://pancake.io/1e79d0/errorfunction.html
http://pancake.io/1e79d0/exception.html
http://pancake.io/1e79d0/fenv.html
http://pancake.io/1e79d0/file.html
http://pancake.io/1e79d0/functional.html
http://pancake.io/1e79d0/gammafunction.html
http://pancake.io/1e79d0/getopt.html
http://pancake.io/1e79d0/index.html
http://pancake.io/1e79d0/intrinsic.html
http://pancake.io/1e79d0/isemail.html
http://pancake.io/1e79d0/json.html
http://pancake.io/1e79d0/linux.html
http://pancake.io/1e79d0/linuxextern.html
http://pancake.io/1e79d0/loader.html
http://pancake.io/1e79d0/locale.html
http://pancake.io/1e79d0/math.html
http://pancake.io/1e79d0/mathspecial.html
http://pancake.io/1e79d0/md5.html
http://pancake.io/1e79d0/metastrings.html
http://pancake.io/1e79d0/mmfile.html
http://pancake.io/1e79d0/numeric.html
http://pancake.io/1e79d0/object.html
http://pancake.io/1e79d0/outbuffer.html
http://pancake.io/1e79d0/parallelism.html
http://pancake.io/1e79d0/path.html
http://pancake.io/1e79d0/perf.html
http://pancake.io/1e79d0/process.html
http://pancake.io/1e79d0/processinit.html
http://pancake.io/1e79d0/pthread.html
http://pancake.io/1e79d0/random.html
http://pancake.io/1e79d0/range.html
http://pancake.io/1e79d0/regex.html
http://pancake.io/1e79d0/regexp.html
http://pancake.io/1e79d0/signals.html
http://pancake.io/1e79d0/socket.html
http://pancake.io/1e79d0/socketstream.html
http://pancake.io/1e79d0/sqlite3.html
http://pancake.io/1e79d0/stdarg.html
http://pancake.io/1e79d0/stddef.html
http://pancake.io/1e79d0/stdint.html
http://pancake.io/1e79d0/stdio.html
http://pancake.io/1e79d0/stdiobase.html
http://pancake.io/1e79d0/stdlib.html
http://pancake.io/1e79d0/stream.html
http://pancake.io/1e79d0/string.html
http://pancake.io/1e79d0/syserror.html
http://pancake.io/1e79d0/system.html
http://pancake.io/1e79d0/termios.html
http://pancake.io/1e79d0/time.html
http://pancake.io/1e79d0/tipc.html
http://pancake.io/1e79d0/traits.html
http://pancake.io/1e79d0/typecons.html
http://pancake.io/1e79d0/typelist.html
http://pancake.io/1e79d0/typetuple.html
http://pancake.io/1e79d0/uni.html
http://pancake.io/1e79d0/uni_tab.html
http://pancake.io/1e79d0/unittest.html
http://pancake.io/1e79d0/uri.html
http://pancake.io/1e79d0/utf.html
http://pancake.io/1e79d0/variant.html
http://pancake.io/1e79d0/wcharh.html
http://pancake.io/1e79d0/xml.html
http://pancake.io/1e79d0/zip.html
http://pancake.io/1e79d0/zlib.html