DDoc and logically structured HTML

[Stewart Gordon]

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.

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++.

> 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?

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?

> 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.

> 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.

> 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?

Replacing the current format would be a breaking change.

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.

Stewart.