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.
