DDoc and logically structured HTML

[Ary Manzana]

On 03/11/2012 05:33 PM, Stewart Gordon wrote:
> On 11/03/2012 19:04, Ary Manzana wrote:
> <snip>
>> I don't understand why you related dynamic class' loading with a
>> documentation
>> system/syntax for D.
>
> Because that's what Javadoc relies on as a means for a program
> distributed in binary form to call custom code.

What do you mean by "custom code"?

>
> OK, so there are native ways to do this, like DLLs and SOs. I don't
> really know whether these are fit for the purpose. It might get a bit
> complicated supporting the D object model with DMD being written in C++.

Sorry, I still don't understand you :-(

>
>> Some hours ago you closed a very old enhancement report I submited:
>>
>> http://d.puremagic.com/issues/show_bug.cgi?id=3161
>>
>> (in fact I had totally forgotten I implemented that :-P, so thanks for
>> reminding it to
>> me... thought I didn't like that you closed it as invalid)
>>
>> Now, I implemented it purely based on dmd's code. I didn't add
>> anything else to get that
>> done. And D is not dynamic or doesn't have dynamic class loading.
>
> OK, so writing a new documentation generator based on the DMD front end
> code is another approach. Did you just write it in C++, or do the extra
> work so that you could write it in D?

I wrote it in Java, because back then I had dmd ported to Java and I 
found it easy to do it that way (I'm not very efficient/fast programming 
in C++).

>
> Either way, it's good that you've written a D documentation generator
> that's better than standard Ddoc, and no doubt handles D much better
> than Doxygen does. Have you released it anywhere?

I posted it back then, it's in Descent's source code. There wasn't much 
interest, though. And instead of working on a decent documentation 
system you end up with documentation like this one:

https://github.com/D-Programming-Language/phobos/blob/master/std/algorithm.d#L4

Nice, a javascript tag inside of the docs. And then an excerpt:

$(BOOKTABLE ,
$(TR $(TH Category) $(TH Functions)
)
$(TR $(TDNW Searching) $(TD $(MYREF balancedParens) $(MYREF

???

Ok, a table can't be done easily in markdown or rdoc either, but a list 
would have maybe been enough. Or just list the functions in alphabetical 
order, top down (because it's hard to do a binary search with the eyes 
from left to right, since it takes some time to spot the first letter of 
every word). Like finding join here:

http://dlang.org/phobos/std_array.html

instead of here:

http://pastebin.com/ib4dJt48

>
>> So... can you explain a bit more?
>>
>> And does somebody know why, being dmd able to compile files, which
>> requires having exact
>> type information for every method/template,whatever, generates such a
>> poor documentation?
>
> I guess because not that much work has gone into Ddoc so far.

Documentation is the primary interface to the users of a library, 
including the standard library. I believe it deserves a lot more 
attention than that.

>
>> Another question: ddoc is used (or was used) to generate d's main
>> site. Wut?? So it's much
>> more than just documenting D classes. I think this is wrong. That's
>> when you end up having
>> macros and all of that, because when generating a page you want to
>> reuse things. But when
>> documentation a library, hmmm... I never needed such thing. And even
>> though I do care
>> about the format of the documentation (how it looks), I definitely
>> don't put formatting
>> information inside a method's documentation (except for code snippets
>> and lists).
>
> By "formatting information" are you talking about semantic/logical
> markup or presentational/physical markup?
>
> http://webtips.dan.info/logical.html
> talks about the differences between them - written from an HTML point of
> view but I suppose equally applicable to Ddoc macros.

Interesting reading.

I talk about semantic/logical markup. But I'd like to use one which, 
when I read it, doesn't hurt my eyes (like std.algorithm docs).

>
>> Some simple like markdown or rdoc (well, the idea, not rdoc itself for
>> D :-P) should be
>> more than enough.
>>
>> If there's interesent, I can hack dmd into producing such
>> documentation, and send a pull
>> request.
>
> To replace the current Ddoc comment format, or to give the user the
> choice between that and whatever else?

Replace it. Macros to document code? I think that's a bit too much...

Write a list in DDoc:

$(UL
   $(LI Karatsuba multiplication)
   $(LI Squaring is optimized independently of multiplication)
   $(LI Divide-and-conquer division)
   $(LI Binary exponentiation)
)

Write a list in rdoc or markdown:

* Karatsuba multiplication
* Squaring is optimized independently of multiplication
* Divide-and-conquer division
* Binary exponentiation

Or links. With DDoc:

$(WEB sgi.com/tech/stl/, Alexander Stepanov's Standard Template Library)

With markdown

[Alexander Stepanov's Standard Template Library](sgi.com/tech/stl/)

(well, I admit there's not much difference in this last example. 
Still... it's shorter and cleaner :-P)

>
> Replacing the current format would be a breaking change.

Only for docs that heavily use macros. I hope there's not many!

And you can always make a tool to convert ddoc to the new format (I 
believe with ddoc macros?)

>
> Having two formats built into DMD would seem silly, aside from the
> question of how you would specify which is being used in a given
> project. The idea of Ddoc is that it's the standard D way of doing
> documentation. If a compiler has built-in documentation generation, it
> should use either a format that is part of the language standard or some
> established format such as Doxygen, rather than some non-portable ad-hoc
> format. Which is what what you're thinking of doing would be, unless
> it's incorporated into the language standard. But having two
> documentation comment formats in the language standard is itself
> something that doesn't seem to make sense. It would be like the whole D
> language having two syntaxes.

Just leave one syntax.