Mockup of my doc dream ideas

[Adam D. Ruppe via Digitalmars-d]

I wrote this manually as a mock of what I really want the docs to 
look like. I only marked up the top box and a wee bit of the 
bottom. The body text of the doc is written by us and is OK, but 
the function signature is a mess.

My mock:
http://arsdnet.net/mydoc.html

Verily, this is the status quo:
http://dlang.org/phobos/std_algorithm_searching.html#findSkip


First, you'll notice a big difference visually: the function 
signature is formatted in my example. The current thing is a mess 
of text.

I find one param per line to be much more readable, and this has 
precedent in professional documentation like Windows:

https://msdn.microsoft.com/en-us/library/windows/desktop/ms632679%28v=vs.85%29.aspx


When you start adding more default argument stuff, the break up 
per line makes a huge, huge difference IMO.

Next, observe the highlighted words... and go ahead and try to 
click on them. Oh snap! They are links to the language features 
used. This is the web, let's link all over the place. I want to 
have relevant conceptual overviews available one click away on 
every function.

The "would you like to know more" bit isn't just a Starship 
Troopers film reference, but also a bit of important information 
(not actually written in the mock) about the idiom used there. I 
know D about as well as anyone, and I had to pause for a second 
to realize what that constraint *actually* meant. Let's just 
explain it in a link. Ideally, that'd be written by the function 
author in a section of the doc that can link in, but if nothing 
else, recognized patterns can link to generic idiom explanations.


Don't put that mouse down yet! Hover over the template args 
section. Behold the tooltip title. A little thing but maybe 
useful.

And then the coup de grace: mouse over "R1" or "haystack" in the 
definition... notice how it highlights the other occurrences of 
it?

Since the signature is incomplete without the template args, the 
runtime args, AND the constraint, I wanted some way to tie them 
all together visually.

They come in three parts of the signature and cannot be easily 
combined by space, but the mouse over highlighting can draw your 
eye's attention to them from out of the crowd of text.

Mouse over R1 and you instantly see it is the first param and 
referenced as a forward range in the constraint. Constraints are 
too loose to automate much more than this, but just seeing it 
there without having to swim through every word will help you tie 
it together in your squishy puny human brain.



There's a fair chunk of writing to actually realize the 
overviews, but the highlighting and formatting stuff can be done 
automatically. I've started work on a program, using Brian 
Schott's libdparse, to see what I can do to this end but I'm 
exceedingly busy with a million things.

And I am up two hours past bed time again, ttyl all.