Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

On Thursday, 31 December 2015 at 06:39:27 UTC, Israel wrote:
> This is what hits me the most. Thats why we suggested "user 
> contributed examples". PHP docs is the only place ive seen 
> this. What is your stance on this and if you agree, how would 
> you implement it? How would it work?

I do not agree with comments, but I do agree with making user 
submissions easy.

What I am envisioning right now is a kind of suggestion box thing 
on an individual page, where you can write up a bug report, an 
example, a comment, whatever, and have it emailed to me for 
further consideration. I'll do a quick fact-check editing then 
add it to the page.

Of course, you can also continue to submit pull requests through 
github (and I'd encourage this for bigger contributors), but just 
emailing your thoughts to me has a lower barrier of entry.

If we do a good job with the actual docs, you won't need 
comments. And better yet, you won't have to read through dozens 
of old ones to find the thing you need. On PHP, I find the 
comments list is too long and of too low of an average quality to 
be worth reading most the time.


The other important thing is being able to add new pages with 
ease. I just dreamed up this plan while in bed last night: a new 
page would be a D file with a huge leading comment and a bunch of 
documented unit tests. (Why a regular D file? Because then we can 
reference it by its name, it can be listed in the package listing 
automatically, and you can actually compile it to test the code 
without any extra extraction work!)

A comment at the top of "// just docs: Some Page Title" tells the 
generator to format it as a page rather than a normal module 
(this means the title in the comment will be used instead of the 
module name and it will have a table of contents of text sections 
instead of D classes, structs, and other members.)



I'll make a web service where you can upload your .d file and get 
an instant preview. This way, you can render it without needing 
to figure out how to install my doc generator and build the 
website on your own computer. Just submit the form.

Then, if you like it, you can either email the file to me and 
I'll take it from there, or submit a pull request to add your 
file.

The PR will only need to do:

git checkout -b my_new_file
git add my_new_file.d
git commit my_new_file.d -m 'add my new file!'
git push


No need to edit other macro files, build files, TOC files, 
whatever. My infrastructure takes care of that automatically. 
(via build **/*.d. It isn't rocket science and it baffles me that 
the official D system is so convoluted.)


What do the files look like? Well, I'm still working on nailing 
this down, but it is basically a hybrid of markdown and ddoc, but 
it does NOT support ddoc's custom macros. First off, I think they 
are a mess with everyone defining the same all over (look at 
Phobos, it gets confusing) and secondly it makes doing semantic 
analysis of the text harder since a ddoc macro is freeform. With 
unlimited macros, any $ or comma in the text might be significant 
syntax! That's a pain.

And it leads to bugs. Take a look at the References section here:

http://dlang.org/phobos/std_base64.html

It says "RFC 4648 - The Base16". The title is actually longer 
than that... it just had a comma in it and ddoc thought that 
meant end of argument.

There *are* ways to handle this in ddoc, of course, and they 
aren't even really hard. I deal with it every week in the TWID 
source. But it is just one little example of a bigger problem 
that limits how much automatic processing we can do. Not worth it.


Anyway, this is what contributed article file might look like. It 
continues to the end of this email:

// just docs: Introduction to my new doc system
/++

This is the intro line.

An intro paragraph. This is seen on the article listing too. Then 
leave two blank lines gap for the table of contents.


Now you start writing details. You can have headers, code 
examples, and so on like in any other doc.

$(H2 The headers look like ddoc macros)

They translate to the corresponding HTML and are parsed to form a 
table of contents which is automatically inserted in the blank 
area you left above.

$(H3 You can descend in with headers)

This section would be a sub-section of the H2 above.

$(H2 References and code)

You reference items with $(REF std.xml) and write code with 
`markdown style` or

---
ddoc style
---

More to come as it develops.

+/
module mydocs.intro; // you give it a D name to refer to in refs

/// you can also include documented unittests as full examples
/// that will be attached. I need to think of some way to
/// reference them in the text. If only D had named unittests!
unittest {
    // this code can actually be compiled with dmd -unittest
    // right out of the box to keep your examples working well.
}

// all done.