www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - DDoc Improvments

reply Pragma <eric.t.anderton gmail.com> writes:
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:


was simply raw output before)
D_PARAM         = $1 $(I $0)\n
DDOC_PSYMBOL    = $1 $(U $0)\n


problem)
D_PARAM         = <a href='$2.html'>$1<a/> $(I $0)\n
DDOC_PSYMBOL    = <a href='$2.html'>$1</a> $(U $0)\n


anchor name)




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
Apr 30 2008
parent reply Jason House <jason.james.house gmail.com> writes:
Pragma wrote:


 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.



I like the idea of xml with style sheets for ddoc too.  Done right, that
might even help out the IDE developers...  I think there was some
discussion about extracting basic (parsed) information.
Apr 30 2008
parent reply Tower Ty <tytower hotmail.com.au> writes:
You are probably all over this but have you noticed Candydoc html files when
opened have the page you are looking at and behind the package tab you are
linked to every other candydoc produced html file produced at the same time .

i didn't notice this at first but it is a boon for my IDE, KDevelop ,so please
retain it.
May 01 2008
parent reply Pragma <eric.t.anderton gmail.com> writes:
Tower  Ty Wrote:


 You are probably all over this but have you noticed Candydoc html files when
opened have the page you are looking at and behind the package tab you are
linked to every other candydoc produced html file produced at the same time .
 
 i didn't notice this at first but it is a boon for my IDE, KDevelop ,so please
retain it.


FWIW, I started hacking up a copy of DMDFE last night (Thanks Walter and
Gergor), and am now sinking my teeth into the ddoc internals.  It's actually
not that bad, and is turning out to be just the kind of lightweight project I
need while I'm working on other stuff.  My hope is to have something that can
be handed to Walter as a patch, or rolled into a stand-alone tool like rebuild.

I've already added $(LF) and $(TAB) macros to help make ddoc code easier to
format.  I also plan on adding a $(DDOC_EXT) macro to specify the doc file
extension; that way you can write xml.ddoc, xhtml.ddoc, html.ddoc, rtf.ddoc,
etc. and get the output you'd expect.

The hardest part has been figuring out how to render the various pieces of
information associated with a given declaration.  The ddoc embedded code parser
itself is also another challenge since it references the same macros used by
the rest of the processor, but is rather myopic when it comes to digesting
tokens.

- Pragma
May 01 2008
parent reply Jason House <jason.james.house gmail.com> writes:
Pragma wrote:


 Tower  Ty Wrote:
 

 You are probably all over this but have you noticed Candydoc html files
 when opened have the page you are looking at and behind the package tab
 you are linked to every other candydoc produced html file produced at the
 same time .
 
 i didn't notice this at first but it is a boon for my IDE, KDevelop ,so
 please retain it.


 
 FWIW, I started hacking up a copy of DMDFE last night (Thanks Walter and
 Gergor), and am now sinking my teeth into the ddoc internals.  It's
 actually not that bad, and is turning out to be just the kind of
 lightweight project I need while I'm working on other stuff.  My hope is
 to have something that can be handed to Walter as a patch, or rolled into
 a stand-alone tool like rebuild.


Cool.  Good luck!
May 01 2008
parent reply pragma <eric.t.anderton gmail.com> writes:
Jason House wrote:

 Pragma wrote:
 

 Tower  Ty Wrote:


 You are probably all over this but have you noticed Candydoc html files
 when opened have the page you are looking at and behind the package tab
 you are linked to every other candydoc produced html file produced at the
 same time .

 i didn't notice this at first but it is a boon for my IDE, KDevelop ,so
 please retain it.


 FWIW, I started hacking up a copy of DMDFE last night (Thanks Walter and
 Gergor), and am now sinking my teeth into the ddoc internals.  It's
 actually not that bad, and is turning out to be just the kind of
 lightweight project I need while I'm working on other stuff.  My hope is
 to have something that can be handed to Walter as a patch, or rolled into
 a stand-alone tool like rebuild.


 
 Cool.  Good luck!


Thanks.  I'll need it.  So far I have dmdfe doing verbose output for 
declarations, but I'm having a hell of a time trying to pin down the 
basic return type for methods.  Also, when done, DDOC_DECL will take a 
whopping 9 or 10 arguments - so I'm considering hacking in named 
arguments (as opposed to numeric/positional) as way to possibly make 
less verbose ddoc code more manageable.

I think this output chunk speaks for itself:

---- output (snippet) ----

<decl kind="function" protection="public" prefix="final synchronized" 
name="function2" namespace="foo.bar.baz" type="void(int x)" pretty="void 
function2(int x)" mangled="_D3foo3bar3baz9function2FiZv">

---- xml.ddoc (snippet) ----
DDOC_DECL      = <decl kind="$1" protection="$2" prefix="$3" name="$4" 
namespace="$5" type="$6" pretty="$7" mangled="$8">
DDOC_DECL_DD   = $0</decl>


----- test2.d (snippet) ----
module foo.bar.baz;
synchronized final void function2(int x){ /*...*/ }
May 01 2008
parent boyd <gaboonviper gmx.net> writes:
Wow, that's cool, and exactly what I've been looking for. Good luck  =

working it out.

Cheers,
Boyd

--------
On Fri, 02 May 2008 05:16:28 +0200, pragma <eric.t.anderton gmail.com>  =

wrote:


 Jason House wrote:

 Pragma wrote:


 Tower  Ty Wrote:


 You are probably all over this but have you noticed Candydoc html  =









 files
 when opened have the page you are looking at and behind the package=








  =


 tab
 you are linked to every other candydoc produced html file produced =








at  =


 the
 same time .

 i didn't notice this at first but it is a boon for my IDE, KDevelop=








  =


 ,so
 please retain it.


 FWIW, I started hacking up a copy of DMDFE last night (Thanks Walter=






  =


 and
 Gergor), and am now sinking my teeth into the ddoc internals.  It's
 actually not that bad, and is turning out to be just the kind of
 lightweight project I need while I'm working on other stuff.  My hop=






e  =


 is
 to have something that can be handed to Walter as a patch, or rolled=






  =


 into
 a stand-alone tool like rebuild.


  Cool.  Good luck!


 Thanks.  I'll need it.  So far I have dmdfe doing verbose output for  =



 declarations, but I'm having a hell of a time trying to pin down the  =



 basic return type for methods.  Also, when done, DDOC_DECL will take a=


  =


 whopping 9 or 10 arguments - so I'm considering hacking in named  =



 arguments (as opposed to numeric/positional) as way to possibly make  =



 less verbose ddoc code more manageable.

 I think this output chunk speaks for itself:

 ---- output (snippet) ----

 <decl kind=3D"function" protection=3D"public" prefix=3D"final synchron=


ized"  =


 name=3D"function2" namespace=3D"foo.bar.baz" type=3D"void(int x)" pret=


ty=3D"void  =


 function2(int x)" mangled=3D"_D3foo3bar3baz9function2FiZv">

 ---- xml.ddoc (snippet) ----
 DDOC_DECL      =3D <decl kind=3D"$1" protection=3D"$2" prefix=3D"$3" n=


ame=3D"$4"  =


 namespace=3D"$5" type=3D"$6" pretty=3D"$7" mangled=3D"$8">
 DDOC_DECL_DD   =3D $0</decl>


 ----- test2.d (snippet) ----
 module foo.bar.baz;
 synchronized final void function2(int x){ /*...*/ }
May 02 2008