[Help-source-highlight] cross-linking all mentioned source files for API generation?

[Britton Kerin]

Hi.  I'm using source-highlight to generate API docs straight from headers,
sort of like Robodoc, doxygen etc but withouth having to mark everything up.
And you can drill down into the sources at need.

This works really nice I think with a few small issues.  One is that it would be
nice to be able to automatically make links from all explicit mentions of source
files. Right now I post-process the generated HTML like this:

# Generate cross linked header and source files as a simple form of API
# documentation (and for browsable source).
.PHONY: xlinked_source_html
xlinked_source_html:
        rm -f $@/*.[ch]
        find . -name "*.[ch]" -exec cp \{\} $@ \;
        cd $@ ; source-highlight --gen-references=inline *.[ch]
        # This gets a bit wild.  We use ||= to take advantage of non-lexical
        # vars which aren't reinitialized every time through implicit -p loop,
        # to save prohibitively expensive per-line recomputation of known file
        # name regular expression.  The link-for-filename substitution has a
        # negative look-ahead assertion which trims off some file name text
        # that source-highlight itself produces.
        cd $@ ; \
          perl -p -i \
            -e '$$fre ||= join("|", split("\n", `ls -1 *.[ch]`));' \
            -e '$$fre_dot_escape_done ||= ($$fre =~ s/\./\\./g);' \
            -e 's/((?:$$fre)(?!\.html|\:\d+))/<a href="$$1.html">$$1<\/a>/g;' \
            *.html
        rm $@/*.[ch]

I'm not sure exactly how source-highlight could go about building this sort
of thing in.  Or maybe it already does and I missed it somehow.

Also, in those cases where source-highlight generates in-line references
to multiple different functions (presumably because multiple ctags database
entries exist for a symbol) it might be nice to be able to provide some sort
of explicit disambiguation hint in the sources themselves.  The ambiguity
is or course the result of processing everything together, but other strategies
are more complicated.  A small feature like this would let you get about what
you do from doxygen or the like without having to instrument every function,
but only a few in select places for disambiguation.

Just random thoughts.

Britton