-
Notifications
You must be signed in to change notification settings - Fork 31
Documentation Tooling #12
Comments
Notes on tools: there have been two attempts to unbundle the existing doc tool from the core repo.
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. |
👍 for link checking. It would also be good to check if a page exists that is not linked to from anywhere. |
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? |
@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!) |
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. |
I would like to have things such as 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 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 |
Closing this in favor of #61 |
Hi – I'm taking this task for myself.
I'm going to investigate documentation tooling for this repository.
Goals:
It's pretty likely these'll live as
npm
scripts (npm test
,npm start
,npm run export
, etc.)The text was updated successfully, but these errors were encountered: