March 29, 2012
> This is precisely the wrong way to fix this.  DDoc needs to be fixed in the compiler.  It's one of the lowest hanging fruits I think we have (a great concept (using compiler knowledge of code structure to generate documentaiton) that is poorly implemented).
>
> -Steve

Would be a good change to move from ugly macros that make you cry to
something more suitable like pythons sphinx.

The output should be roughly compatible and a pragma(doc, sphinxalike) at the
top of the module lets the compiler use the new system.
March 29, 2012
The ddoc macros can do a LOT better than it looks
in phobos.
March 29, 2012
On Thu, 29 Mar 2012 16:53:42 -0400, Adam D. Ruppe <destructionator@gmail.com> wrote:

> The ddoc macros can do a LOT better than it looks
> in phobos.

My concern is not with the macros.  The raw data availability and cross linking is severely lacking.  Just the fact that we need javascript to generate the links at the top should tell you something.

-Steve
March 29, 2012
On Thursday, March 29, 2012 17:04:13 Steven Schveighoffer wrote:
> On Thu, 29 Mar 2012 16:53:42 -0400, Adam D. Ruppe
> 
> <destructionator@gmail.com> wrote:
> > The ddoc macros can do a LOT better than it looks
> > in phobos.
> 
> My concern is not with the macros. The raw data availability and cross linking is severely lacking. Just the fact that we need javascript to generate the links at the top should tell you something.

Yeah, compared with other documentation generators, such as doxygen or javadoc, ddoc is pretty weak. The macros work fairly well overall, but not enough gets generated from them. At minimum, links for all of the types and functions in a module in a proper hierarchical format is a must, and ddoc doesn't do anything of the sort.

ddoc is the base of something solid, and its simplicity is a definite plus in many ways, but it could be much more powerful even without adding all of the complication that doc generators such as doxygen have.

- Jonathan M Davis
March 29, 2012
On Thursday, 29 March 2012 at 21:04:13 UTC, Steven Schveighoffer wrote:
> Just the fact that we need javascript to generate the links at the top should tell you something.

It tells the data *is* there, but it needs fancier processing...

We could put fancier stuff in the compiler, but that's kinda
a pain and I worry that it won't fit all needs.

Of course, a table of contents is so obviously useful
that it probably should be in there.

But, I think a more general approach is to fix the default
ddoc output to give as much info as possible, and then
do a standard tool (like rdmd) that expands it more,
and is easy for the users to extend with more info.
1 2
Next ›   Last »