Documentation for any* dub package, any version

Adam D. Ruppe destructionator at gmail.com
Tue Feb 27 02:26:49 UTC 2018


On Tuesday, 27 February 2018 at 01:43:55 UTC, Jonathan M Davis 
wrote:
> Well, then basically, projects are going to need to decide to 
> go with adrdox over ddoc if they want clean documentation.

That's right, and I can't imagine anyone is going to put hours of 
work into ddoc when they can spend seconds just writing and have 
it just work on my site, including most common ddoc in addition 
to a good subset of markdown and, if they decide to dive a little 
bit deeper, can use my custom syntax custom-tailored to writing D 
documentation quickly and easily like [link].

https://www.youtube.com/watch?v=Ak516vtDTEA

> They'll probably get better documentation with adrdox than the 
> default ddoc if they do nothing, but any project that actually 
> goes to the effort of having nice looking documentation is 
> going to fall flat on its face with adrdox unless it buys into 
> adrdox whole hog.

Eh, that's not true. I am *very* compatible with Phobos (have you 
use dpldocs.info before? 9/10 dentists agree, it is vastly 
superior to dlang.org, and the tenth dentist is paid to lie), and 
since most "nicer" ddoc borrows from the phobos definitions, most 
of them will just work too. I actually even just added your LREF2 
macro to the internal macro compatibility list, bringing my 
compatibly with your syntax to near-total.

BTW you misspelled "element" here:
http://dxml.dpldocs.info/source/dxml.dom.d.html#L119

On your version, third paragraph:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_dom.html#.DOMEntity

adrdox (my build here anyway, which knows the whole phobos tree 
too) caught that and issued a broken link warning. Did ddoc? I 
already know the answer.

Of course, if you were using adrdox syntax, that mistake wouldn't 
have happened in the first place, instead of writing:

   $(REF_ALTTEXT EntityType.elementStart, EntityType.elmentStart, 
dxml, parser)

You would have simply wrote [EntityType.elementStart] and not had 
to repeat yourself telling the compiler what it already knows (in 
a bizarre order, no less).


Of course, even with the broken link, the adrdox result is usable:

http://dxml.dpldocs.info/dxml.dom.parseDOM.2.html

links to:
http://dxml.dpldocs.info/dxml.parser.EntityType.html#elmentStart

and you can see it in the table.

Whereas the ddoc link goes to:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_parser.html#.EntityType.elmentStart

where the anchor is who-knows-where.


Moreover, look at this:
http://dxml.dpldocs.info/dxml.util.asNormalized.html

"combines parseStdEntityRef and parseCharRef along with 
processing for $(DCODE_STRING '\r') to"

and compare with:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_util.html#.asNormalized

"combines parseStdEntityRef and parseCharRef along with 
processing for to "


See something missing? Yes, you write DCODE_STRING instead of the 
definition of D_CODE_STRING and ddoc swallowed your text. (Yes, I 
know you can define ddoc to output undefined macros, just like 
adrdox does. But it doesn't by default, so a typo in a macro name 
means text just ~disappears~.)


And again, that is unlikely to have happened if you just used the 
standard backticks (`'\r'`) which don't render exactly the same 
but are good enough. ddoc supports them too, so this isn't even 
an adrdox thing... but I'd argue that merely having user-defined 
macros makes you more likely to try to use them, increasing the 
likelihood for mistakes like this. That's the main reason why I 
decided to simply not support them, the cost outweighs the 
benefits.



I don't say this to pick on you - you have some of the nicest 
ddoc I have ever seen, and you actually make the effort to write 
it all up in the first place.

But even you, who know how to use ddoc very well and have 
obviously spent some time on it here, made trivial mistakes here 
that just don't happen with adrdox.



More information about the Digitalmars-d-announce mailing list