Last week, I posted in the general forum my dream for better D docs. Today, about 4 days of work later, I'm about 1/4 of the way there.

Still a long way to go, but I've already come so far.

First, behold my old dpldocs.info site. Yes, it is still up and now it ties into my new docs! You can use it to quickly jump to a doc given its name:

http://dpldocs.info/

Inspired by the php docs, I also have it able to search direct from a URL. Click this:

http://dpldocs.info/findSkip

and it automatically sends you here:

http://dpldocs.info/experimental-docs/std.algorithm.searching.findSkip.html


I haven't run all of Phobos through my generator yet (it still crashes on some of it) but I have run a lot of it through so you can browse around and get a feel.


I also described why in This Week in D last night: http://arsdnet.net/this-week-in-d/dec-27.html



While I'm still probably at least a month away from having this really finished, I feel it is already a massive improvement on the main docs and wanted to announce it so other people can give it a try too.



Once I finish the generator, I'll start writing new articles to fill in some of the dummy links there, and perhaps make minor changes to Phobos itself (if I can make changes that help me without hurting the existing ddoc based site or source legibility). The new articles are a big part of the work too!

Finally, when I am happy with this program, I will document the doc generator and release it for other people to use too.

But until then, have fun playing with dpldocs.info!

On 12/28/15 3:15 PM, Adam D. Ruppe wrote:
> http://dpldocs.info/
>
> Inspired by the php docs, I also have it able to search direct from a
> URL. Click this:
>
> http://dpldocs.info/findSkip

The signature proper is nice. The formatting of "&&" in the constraint is inconsistent, but I guess that's a matter with the formatting of the code.

The vertical spacing post "Parameters" of http://dpldocs.info/findSkip is annoying. So we have a healthy vertical space between the "Parameters" and "haystack" headings - fine - then a dinghy space between "haystack" and the type, then again a large space between the "Type:" and the description.

I think types should be massaged with the parameter names. Also the type of the return value should be massaged with the heading "Return Value" and the valign of the return value's description should be the same as for the parameters, so we have:

========
Parameters
((vspace 1))
R1 haystack
((hspace 1))The forward range to search in.
((vspace 2))
R2 needle
((hspace 1))The forward range to search for.
((vspace 2))
Return Value (bool)
((vspace 1))
((hspace 1))true if the needle was found, in which case haystack is positioned after the end of the first occurrence of needle; otherwise false, leaving haystack untouched.
========

etc.

Ideally most of these things would be adjustable via css. Even some of the text (e.g. "Return Value" etc.) would be in a perfect world part of the css (there's that property "before" or something).

Essentially it would be fantastic if the docs contained the semantic info and the formatting would be entirely shipped to css.


Andrei

One more note: I salute the initiative of another doc generator and read the motivation behind it. Yet I do think it's worth asking ourselves two questions:

(a) is the new proposed system differentiated enough to justify its existence and motivate others to join in?

(b) are the existent systems reaching hard limits that the proposed system overcomes by design?

Last thing we want is the idyllic Balkanic landscape of several "me too" documentation systems, neither of which is better and has more of a following than others.

This is just musing. Please don't make it into Archduke Ferdinand's assassination :o).


Andrei

On 29/12/15 12:05 PM, Andrei Alexandrescu wrote:
> One more note: I salute the initiative of another doc generator and read
> the motivation behind it. Yet I do think it's worth asking ourselves two
> questions:
>
> (a) is the new proposed system differentiated enough to justify its
> existence and motivate others to join in?

It supports comments on manifest enums sorta like as if it was named.
The others do not ;)

So I'm already very wanting of this solution to say the least.

On Monday, 28 December 2015 at 23:01:05 UTC, Andrei Alexandrescu wrote:
> The signature proper is nice. The formatting of "&&" in the constraint is inconsistent, but I guess that's a matter with the formatting of the code.

Yeah, that is a css bug I just forgot about getting in to everything else, fixed now.

> The vertical spacing post "Parameters" of http://dpldocs.info/findSkip is annoying.

In a simple function it may be unnecessary but doesn't really hurt, while in a complex type or a function with a lot of parameters, it improves legibility. A type alone can be a pretty complex beast and can warrant the use of multiple lines.

I *might* change my mind on this, Qt puts the types on one line, but the real question is what they look like when I finish the constraint analyzer. I haven't even started implementing it yet, but the type of haystack is not really R1. It is actually "duck-typed forward range", which is gleamed from the constraint.

Qt's types are rarely more complex than a class pointer. Sometimes, you might see a QList<QSomething*> or a QMap<QKey, QValue>, but never anything like what Phobos deals in. C++ doesn't have D's const and immutable, it doesn't have the dip 25 ref checker, it doesn't use much design by introspection. Voldemort types both simplify the signature and make the explanation more complex at the same time.

So what works for us may be quite different than what works for them.

But once I get the constraint analyzer set up and try it on more real world code, if it remains legible in complex cases on one line (which it might, I should be able to simplify stuff like `!isInfinite!Range && isForwardRange!Range` into something like "finite forward range"), I'll revisit this.


> Ideally most of these things would be adjustable via css.

Of course, it is primarily an issue of margins, and I'm mostly using the browser defaults for the semantic tags at this point. But I do want it to be good out of the box and find too much space to be better than too little.

> Essentially it would be fantastic if the docs contained the semantic info and the formatting would be entirely shipped to css.

Yes, I agree, that is one of my goals too.

Rikki Cattermole <alphaglosined@gmail.com> wrote:
> On 29/12/15 12:05 PM, Andrei Alexandrescu wrote:
>> One more note: I salute the initiative of another doc generator and read the motivation behind it. Yet I do think it's worth asking ourselves two questions:
>> 
>> (a) is the new proposed system differentiated enough to justify its existence and motivate others to join in?
> 
> It supports comments on manifest enums sorta like as if it was named. The others do not ;)
> 
> So I'm already very wanting of this solution to say the least.
> 

Is this feature unreasonably difficult to integrate within the existing products?

On 29/12/15 4:08 PM, Andrei Alexandrescu wrote:
> Rikki Cattermole <alphaglosined@gmail.com> wrote:
>> On 29/12/15 12:05 PM, Andrei Alexandrescu wrote:
>>> One more note: I salute the initiative of another doc generator and read
>>> the motivation behind it. Yet I do think it's worth asking ourselves two
>>> questions:
>>>
>>> (a) is the new proposed system differentiated enough to justify its
>>> existence and motivate others to join in?
>>
>> It supports comments on manifest enums sorta like as if it was named.
>> The others do not ;)
>>
>> So I'm already very wanting of this solution to say the least.
>>
>
> Is this feature unreasonably difficult to integrate within the existing
> products?

From what Adam has said, definitely won't be happening with DDOC.
There is simply no symbol to attach the comment to.

On Tuesday, 29 December 2015 at 05:00:48 UTC, Rikki Cattermole wrote:
> From what Adam has said, definitely won't be happening with DDOC.
> There is simply no symbol to attach the comment to.

Well, not definitely, it was really easy to do in libdparse (a two line diff) and probably similarly easy in dmd.

There is no user-facing name for an anonymous enum, but there is a compiler data structure for it.

On 30/12/15 3:24 AM, Adam D. Ruppe wrote:
> On Tuesday, 29 December 2015 at 05:00:48 UTC, Rikki Cattermole wrote:
>> From what Adam has said, definitely won't be happening with DDOC.
>> There is simply no symbol to attach the comment to.
>
> Well, not definitely, it was really easy to do in libdparse (a two line
> diff) and probably similarly easy in dmd.
>
> There is no user-facing name for an anonymous enum, but there is a
> compiler data structure for it.

Okay, I remember you saying something a bit different on IRC (at least to my understanding).

On Tuesday, 29 December 2015 at 14:26:48 UTC, Rikki Cattermole wrote:
> Okay, I remember you saying something a bit different on IRC (at least to my understanding).

Well, I'm still a bit iffy on it, to attach a name I used the first member of the enum which might not pass review muster in dmd itself, but you could also probably just generate a random name for it.

Actually, I think dmd *does* generate random names for anonymous enums internally anyway. I know it does for structs and functions etc.

dmd could probably get away without a name too, since it doesn't care about SEO and linking, whereas I do.

But regardless, I'm sure it is technically possible, I'm just not sure the dmd maintainers wouldn't reject it as a pointless hack in their eyes.