On Monday, 26 February 2018 at 20:15:13 UTC, aliak wrote:
> Awesome. good start at least, and just to throw an approach out there for your consideration, a .adrdox.yml file with a include/exclude/style/etc keys might be a good way to go.

Yeah, that's basically what I was thinking (though not yml, I'd use a sane, well-support language. actually I'd probably just use xml.)

> Great! Think I'll give the skeleton/style a hack at some point indeed.

Well, that's if you download and host the stuff yourself. Though my css file is kinda intertwined, it has the mobile responsive stuff in there next to content presentation and syntax highlight colors, etc....

> Maybe if it's a central host then styling should just be homogeneous across the board as well for consistency and all?

yeah, maybe that too.

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
> Many of you will already know this from the other thread or from my twitter, but I just added a on-demand downloader to my dpldocs.info domain to fetch and build docs for any* dub package.

Hi Adam!

Thanks for this superb work!

Trying it onto gtk-d got an error saying to send you the failing link, so here you are :

http://gtk-d.dpldocs.info/cairo.html

A. Corbi

On Monday, 26 February 2018 at 21:16:07 UTC, Antonio Corbi wrote:
> Trying it onto gtk-d got an error saying to send you the failing link, so here you are :

gtk-d is actually just too big for this, so it timed out. But I also already made gtkd docs on the main site:

http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html


gtk is a bit of a special case in part because of its sheer size and in part because it uses C names and special gtk syntax. The generator can translate it though - it just needs a special command line arg which right now means I do it manually.

On Monday, February 26, 2018 19:51:27 Adam D. Ruppe via Digitalmars-d- announce wrote:
> On Monday, 26 February 2018 at 15:49:19 UTC, Jonathan M Davis
>
> wrote:
> > Yeah. Any project that uses .ddoc files to define additional macros isn't going to work properly
>
> It is actually more than that: I don't support user-defined ddoc macros at all. About 3/4 of the ones I've seen are just link macros.... instead of everyone creating their own random mix (like LREF, LREF2, REF, REF_ALTTEXT, PHOBOS_REF, PHOBOS_REF_ALTTEXT, OBJECT_REF...), I just have a built-in, simple, unified syntax: [symbol|alt text] where alt text is optional and symbol is looked up according to D scope rules. (you can also define custom symbols for things like author name links).
>
> I link to the source automatically too, including to the specific line of the correct overload for functions, so no need for macros to do those.
>
> Much easier to write in code: no more need to remember what this project decided to name its macro.
>
> (keep in mind that adrdox is explicitly NOT ddoc. I dropped a few ddoc misfeatures and modified some in a non-compatible way. I've given up on trying to save ddoc, it is rotten to the core.)

Well, then basically, projects are going to need to decide to go with adrdox over ddoc if they want clean documentation. 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.

dxml would be a prime example of a project that won't work with adrdox though given that it tries to emulate what Phobos has done with its documentation, and many of the macros are the same, which should minimize how much the documentation will have to be mucked with if it ever ends up in Phobos, but that means that it is very much not vanilla ddoc, let alone adrdox.

- Jonathan M Davis

On Mon, Feb 26, 2018 at 06:43:55PM -0700, Jonathan M Davis via Digitalmars-d-announce wrote: [...]
> Well, then basically, projects are going to need to decide to go with adrdox over ddoc if they want clean documentation. 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.
> 
> dxml would be a prime example of a project that won't work with adrdox though given that it tries to emulate what Phobos has done with its documentation, and many of the macros are the same, which should minimize how much the documentation will have to be mucked with if it ever ends up in Phobos, but that means that it is very much not vanilla ddoc, let alone adrdox.
[...]

It's a sorry state of affairs.  I dream of the day when I can just write code and documentation as-is, and downstream users can just use whatever doc formatting system they like and it will all Just Work(tm).

Basically, it requires a standard way of writing documentation that every backend tool understands and supports, be it ddoc or adrdox or whatever else you fancy.  But I'm not holding my breath for that to materialize.


T

-- 
Unix is my IDE. -- Justin Whear

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
> Many of you will already know this from the other thread or from my twitter, but I just added a on-demand downloader to my dpldocs.info domain to fetch and build docs for any* dub package.
>
> [...]

This is really awesome. It would be really cool if this could feedback a coverage score to code.dlang.org that indicates the level of documentation in a library. Something like the % of functions/classes/modules that are documented and if there are any missing parameters/warnings during the parsing of docs.

Cheers,
Norm

On Monday, February 26, 2018 17:53:23 H. S. Teoh via Digitalmars-d-announce wrote:
> On Mon, Feb 26, 2018 at 06:43:55PM -0700, Jonathan M Davis via Digitalmars-d-announce wrote: [...]
>
> > Well, then basically, projects are going to need to decide to go with adrdox over ddoc if they want clean documentation. 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.
> >
> > dxml would be a prime example of a project that won't work with adrdox though given that it tries to emulate what Phobos has done with its documentation, and many of the macros are the same, which should minimize how much the documentation will have to be mucked with if it ever ends up in Phobos, but that means that it is very much not vanilla ddoc, let alone adrdox.
>
> [...]
>
> It's a sorry state of affairs.  I dream of the day when I can just write code and documentation as-is, and downstream users can just use whatever doc formatting system they like and it will all Just Work(tm).
>
> Basically, it requires a standard way of writing documentation that every backend tool understands and supports, be it ddoc or adrdox or whatever else you fancy.  But I'm not holding my breath for that to materialize.

Basically, it requires that you do _nothing_ by hand - so no ddoc macros - and the tools figure it all out from the json output from the compiler. As soon as you start marking up the documentation in any way, unless it's a way that _all_ of the tools understand, it's not going to work. And doing something like using macros to generate links like Phobos or dxml do is instant death to that - the same goes with adrdox's markup for links, though that is more automated, so it would be possible to make that understood by more tools, whereas links for ddoc macros are too specific for that.

ddoc does a good job of doing some of the basics, and it provides a way to have really nice documentation if you go the extra mile (including using additional tools to generate stuff like navigation bars to navigate between modules), but it utterly fails as a way to just generate really nice documentation. For that, it would have to process the entire project at once and not be file-centric like it is now. It would also have to do more for you and leave less to macros.

Ultimately, I think that it's going to be up to each project to choose which tool or combination of tools to use to generate their documentation, and any time that anyone doesn't bother to figure that out, you're going to get a subpar result - though ddox and adrdox will likely result in better documentation with no effort than pure ddoc will, since they do stuff like generate the navigation bar for you.

Once I've cleaned it up and documented it, I'm actually planning on releasing what I did for dxml as project on github so that it will be possible for anyone's project to easily have documentation like dxml does (including the navigation bar), though like Phobos, it requires manually using linking macros, since it's just ddoc with a helper program to generate the pieces that you can't do with macros. If you want documentation without any attempt to mark anything up, ddox is probably your best bet.

- Jonathan M Davis

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.

On Tuesday, 27 February 2018 at 02:07:34 UTC, Norm wrote:
> This is really awesome. It would be really cool if this could feedback a coverage score to code.dlang.org that indicates the level of documentation in a library. Something like the % of functions/classes/modules that are documented and if there are any missing parameters/warnings during the parsing of docs.

Maybe, though I don't think computer analysis can say if docs are good (at least not with simple code I'd be likely to write). Like there might be a lot of public functions deliberately undocumented because they are of alpha quality and not supported, but still available in case advanced users want to dive in.

But just having docs generated automatically that users can click on and peruse will give the human a chance to quickly and easily evaluate the package.

On Tuesday, February 27, 2018 02:26:49 Adam D. Ruppe via Digitalmars-d- announce wrote:
> 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.

Any time you do something manually instead of it being automatic, there's a risk of that.

And if adrdox works well for folks, then great. Personally, I'd like to stick to the official tool, especially when I'm writing something that might make it into Phobos (though like Phobos, I was forced to add a helper program in order to deal with stuff like the navigation bar), but there are definitely aspects of it which make it harder to use than adrdox or ddox.

Thanks for pointing out those mistakes.

- Jonathan M Davis