I made it all the way through. Some edits are above Root node because I tried to clean up the links a little bit, to make it easier to just throw in links to different parts of the documentation, and address some of the clarifications you made.
Here is installment two of edits -- this time up to `Root` node ~ line 840. I have more points for you think about, too:
Documentation style concerns:
- This time I tried to clarify the headings (which will also clarify their # links) by prefixing properties and methods with a reference to the thing they're attached to. Please look that over and see if you like it, or if there is another style that you would prefer. I think that *something* has to be there ---- for instance, to differentiate one `map` from another. Otherwise, links won't be reliable and you will have to scroll up to see which section you are in to understand which method you are looking at.
- Notice that on 667 (and some following places) I added `[]` brackets around an optional argument. I think that it is important to distinguish optional arguments. I also think that it would be important to document the expected types of each argument (e.g. string, array of strings, boolean) for every method. That would be fastest I'm sure if you did it, @ai, since you know the API best.
Clarification:
- The list module examples seem weird to me. Are those real use cases?
- The last `node.source` example also seems weird given the text above it. Shouldn't it illustrate cloning a node, or setting its source manually?
- I don't understand the `defaultType` stuff with `node.style()`, ~538.
- I don't understand what 550-551 mean (about containers).
- See line 768: I don't understand the `fast` option --- what was there before did not make sense to me.
If you could clear up all those points, that would be great. At some point I will try to finish the rest (it's a *long* document!)
I just read the first 175 lines tonight and proposed changes. I also have a few questions:
- Have you thought about documenting more specifics about parameters, e.g. expected types, whether they're optional or not, and defaults? That information is generally useful.
- I'm not certain whether my change at line 131 is fully accurate --- please have a look (presumably you'll look at all the changes.)
Nice job @ai. If you think this was useful I will look at the rest of the doc next chance I have! If there's anything you'd like me to do differently, just let me know.
Andrey Sitnik