tools: fix json doc generate error caused by type loose_item_start #5943
Conversation
Current processList function in tools/doc/json.js does not recognise
{"type":"loose_item_start"}. Fix it.
mscdex
added
doc
|
cc @nodejs/documentation |
|
LGTM. This |
|
It's because of such content that appeared recently in doc: ## fs.readdir(path[, options], callback)
* `path` {String | Buffer}
* `options` {String | Object}
* `encoding` {String} default = `'utf8'`
* `callback` {Function}
* `path` {String}
* `callback` {Function}Such format produces ## Heading
* item0
* item1[{"type":"list_start","ordered":false},{"type":"loose_item_start"},{"type":"text","text":"item0"},{"type":"list_item_end"},{"type":"loose_item_start"},{"type":"text","text":"item1"},{"type":"space"},{"type":"list_item_end"},{"type":"list_end"}] |
This makes several changes:
1. Allow path/filename to be passed in as a Buffer on fs methods
2. Add `options.encoding` to fs.readdir, fs.readdirSync, fs.readlink,
fs.readlinkSync and fs.watch.
3. Documentation updates
For 1... it's now possible to do:
```js
fs.open(Buffer('/fs/foo/bar'), 'w+', (err, fd) => { });
```
For 2...
```js
fs.readdir('/fs/foo/bar', {encoding:'hex'}, (err,list) => { });
fs.readdir('/fs/foo/bar', {encoding:'buffer'}, (err, list) => { });
```
encoding can also be passed as a string
```js
fs.readdir('/fs/foo/bar', 'hex', (err,list) => { });
```
The default encoding is set to UTF8 so this addresses the
discrepency that existed previously between fs.readdir and
fs.watch handling filenames differently.
Fixes: #2088
Refs: #3519
PR-URL: #5616
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Trevor Norris <trev.norris@gmail.com>
|
@silverwind I think this is some weird merging mistake during some work on fs. Seems like the older commit was merged first and then git was adding the older more incomplete version as addition. In any case the docs at the above line number are just wrong and would need to be fixed. See comment on @jasnell commit above. @firedfox's commit seems legit anyhow, since it's just adding the case if it was intentional. LGTM |
|
Oh I thought those duplicated comments were added on purpose. Should I make another PR to remove them from doc? |
|
I am not sure, but it seems very likely. |
|
Thanks! Landed in 05b3a0b. |
|
is this something we want for lts? |
|
@thealphanerd It fixes an edge case that manifested after #5616. I'd say it's nice to have in LTS as a safeguard. |
Pull Request check-list
make -j8 test(UNIX) orvcbuild test nosign(Windows) pass withthis change (including linting)?
If this change fixes a bug (or a performance problem), is a regressiontest (or a benchmark) included?
Is a documentation update included (if this change modifiesexisting APIs, or introduces new ones)?
Affected core subsystem(s)
Description of change
fixes #5942