DDoc Improvments

[Pragma]

This post is intended to foster some discussion about DDOC.  The richness of DDOC's output is an old gripe of mine, but maybe we can get some traction on a better solution than what we have now.

In short: I'd love to digest DDOC generated content as raw XML, so I can compose cross-references for large (tango-sized) projects.  CandyDoc does a lot to replace some of the things that are left out, but I can't help but feel that it's merely a patch to a more fundamental problem with how things are output.  Here's an example.

public void foobar(T:int,U:T)(int x,int y,int z){ /*...*/ }
... Becomes ...
<big>void <u>foobar</u>(T : int,U : T)(int <i>x</i>, int <i>y</i>, int <i>z</i>);</big>

There are several problems with this output:
  - The extraneous "(" and ");" provide rather sizable hurdles to parsing by an XSLT processor, and the oscillation between text and tag elements only makes it harder still.  
  - The template parameters aren't formatted at all, nor are they passed to a discrete macro for handling
  - The types aren't passed to a macro in such a way that they can be formatted or highlighted.

What I would like to propose is to redefine DDOC_PSYMBOL and D_PARAM macros as accepting multiple arguments:

$0 = symbol name
$1 = type name
$2 = fully-qualified symbol module name
$3 = fully-qualified type module name
$4 = symbolic name of the type
$5 = symbolic name of this declaration (if applicable)

While that seems overkill, the possible permutations for the macro now become very handy:

# classic output (note that the type name is now a part of the macro, where it was simply raw output before)
D_PARAM         = $1 $(I $0)\n
DDOC_PSYMBOL    = $1 $(U $0)\n

# anchor suitable for cross-reference (granted, built-in types will be a problem)
D_PARAM         = <a href='$2.html'>$1<a/> $(I $0)\n
DDOC_PSYMBOL    = <a href='$2.html'>$1</a> $(U $0)\n

# anchor with a named anchor for easy browsing (uses symbol name as a unique anchor name)
D_PARAM         = <a href='$2.html#$4'>$1</a> $(I $0)\n
DDOC_PSYMBOL    = <a name='$5'/> <a href='$2.html#$4'>$1</a> $(U $0)\n

# XML output (uses symbolic name as an id for psymbols)
D_PARAM         = <param name='$2.$0' type='$3.$1' typeid='$4'/>
DDOC_PSYMBOL    = <psymbol name='$2.$0' type='$3.$1' typeid='$4' id='$5'/>

This is just the start.  Obviously, there's some holes in this when it comes to built-in types, and attributes like 'public' or 'private' are left completely out.  I'm sure there are many other little things that can be improved for DDOC (named macro arguments come to mind).

That leads me to why I'm posting this here.  I'm looking for any other suggestions that can be heaped on this to help build a more rounded proposal.  Any input would be appreciated.

- Pragma 
- eric.t.anderton -at- gmail