[cfe-dev] clang Specification References

[Daniel Dunbar]

clangers,

I thought it would be nice to have an index of where the source code references
specification documents. This is useful both going from source to the spec
(to find out what we should be doing) and for going from the spec to the source
(to find out what we are doing). I also thought it would encourage annotating the
source and standardizing how we reference the various specification documents.

Here is a prototype based on a simple Python script:
http://keeda.stanford.edu/~ddunbar/clang/references.html

Some notes:
(1) The C99 sections are linked to the .pdf from open-std.org. I use #page= to
try and direct to a nearby page, which works in Acrobat Reader but I'm
not sure what else. It'd be nice to have this work better; the best would be
an HTML version of the spec to link to, but I cannot find one.

(2) The source references link to the doxygen page on llvm.org. I would like to
link to the exact line but doxygen does not spit out regular line information so
this isn't very reliable. Not sure what the easiest way to hack around this is.

I'd appreciate feedback, esp. on how to make the design most useful. I thought
about having two views: one like the current page and another that lists the entire
table of contents. The latter would be useful for scanning for which parts of the
spec we don't reference (and or don't implement). I also experimented with a
tree view to match the table-of-contents but didn't get something I liked.

Also any feedback on how to better hack into doxygen / the specifications would
be great.

If this is deemed useful I think we should drop it into the regular build of doxygen.

- Daniel