Documentation Tooling about docs

[chrisdickinson]

Notes on tools: there have been two attempts to unbundle the existing doc tool from the core repo.

1. I pulled out the tool from io.js at one point.
2. @robertkowalski pulled it out of joyent/node.

I'm unconvinced that we can continue the "hand one file to the doctool, get one file back" approach — we should be checking things in a cross-document fashion (like including table of contents, whether links are broken, canonical named links, etc.) Additionally, the existing tool makes assumptions about the one-to-one-ness of module ⬌ documentation, which we're abandoning here.

[Qard]

👍 for link checking. It would also be good to check if a page exists that is not linked to from anywhere.

[bnb]

Also 👍 for link checking. From the point of view of an inexperienced programmer, it seems like that would add a lot of complexity. Is that not the case?

[chrisdickinson]

@bnb It shouldn't add much complexity. It's just a bit of extra bookkeeping for internal links. I'm not sure how I feel about checking external links, but even that would be pretty simple (it might take a bit longer to run, though!)

[Qard]

I'd pass on external links. Or, at most, make it a separate build task that only warns--other websites will go down, and it's not in our power to know or control exactly when that may happen.

[simov]

IMO we should have a thorough JSON structure in the first place. I just realized that the JSON docs generator actually parses the markdown, which is kind of nice, I guess, but how about having a good JSON structure in the first place?

I would like to have things such as inherits key, that alone will improve the docs dramatically, because you will be able to navigate easily through out the class hierarchy.

What type of object each method is returning, again it should be easy to navigate the hierarchy from there.

What type of object each event receives, same as above.

Also in case a method is accepting a map of options I would like to have each option with its default value and type (just search for "name": "request", in the generated JSON and see for yourself - currently all of it is tossed under the desc key)

Having a thorough JSON structure will allow us to generate markdown, html or just about any other visualization we might think of. The only remaining issue would be how to hook the non machine friendly parts of the docs to that structure (such as text and code examples).

EDIT

{
  "classes": {
    "net.Server": {
      "inherits": "events.EventEmitter",
      "methods": {
        "listed": {

        }
      }
    }
  },
  "utils": {
    "net.createServer": {
      "returns": "net.Server",
      "arguments": {
        "options": {
          "allowHalfOpen": {
            "type": "Boolean",
            "default": false,
          },
          "pauseOnConnect": {
            "type": "Boolean",
            "default": false,
          },
          "required": false
        },
        "connectionListener": {
          "type": "Function",
          "event": {
            "type": "net.Server",
            "name": "connection"
          },
          "arguments": {
            "socket": {
              "type": "net.Socket"
            }
          },
          "required": false
        }
      }
    },
    "net.connect": {
      "returns": "net.Socket",
      "arguments": [
        {
          "port": {
            "type": "Number",
            "required": true
          },
          "host": {
            "type": "String",
            "default": "localhost",
            "required": false
          },
          "localAddress": {
            "type": "String",
            "required": false
          },
          "localPort": {
            "type": "Number",
            "required": false
          },
          "family": {
            "type": "Number",
            "default": 4,
            "required": false
          },
          "connectionListener": {
            "type": "Function",
            "event": {
              "type": "net.Socket",
              "name": "connect"
            }
          }
        }
      ]
    }
  }
}

Wow this took me 10+ minutes, too much work even for writing it in JSON. My idea was to use the type and inherits keys for cross linking between modules. Anyway.

[chrisdickinson]

Closing this in favor of #61