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.

Reply via email to