Node: Certain docs have very little information provided per API

[sagiavinash]

Firstly this is not a rant. I just want to know if its a community decision to have docs this way or there is opportunity for me to contribute to make documentation better.

I am a new to nodejs and i find the nodejs.org/.../docs are very less informative compared to any other big OSS platforms.

for example fs.close api doc is very vague for me.

• Its just listing the arguments fd and callback.
• It would be great to know if the callback has arguments and their details.
• I would want to have an example associated with it.

Can you share thoughts on this perspective, is there any ongoing effort in this area?

[joyeecheung]

I'm definitely +1 on being clearer about the arguments of callbacks. Not just fs though, other callback-heavy APIs like dns, http, etc. all lacks descriptions of callback somewhere, at least a link to a explanation of the convention would be more helpful for people who just cmd+f/ctrl+f across the documentation.

FWIW looks like child_process has a clearer format for explaining these, members of options and arguments of callback are placed in sublists(though I'm not quite sure if putting arguments the same way as object members would be confusing, probably need a little bit more visual hint).

[addaleax]

I just want to know if its a community decision to have docs this way or there is opportunity for me to contribute to make documentation better.

You can find the current source files for the documentation at https://github.com/nodejs/node/blob/master/doc/, and if you want to help improve it, that would be hugely valued! :heart:

The most direct way to do that would be opening pull requests with suggested changes yourself. If you are interested in that, there’s a bit of information on getting started with that at http://nodetodo.org/getting-started/ (you can skip the “build Node” and “ask for a task” parts). We’re also glad to help you here or in the IRC channel listed in our README if you have any questions about this!

You can also open issues like these and ask for clarification, if you prefer.

Firstly this is not a rant.

It doesn’t read like a rant anyway. :)

[jobala]

@joyeecheung @Fishrock123 I would like to give this issue a shot.

[raphaelokon]

Any news on that? Otherwise I could pick it up …

[sam-github]

check out current PRs to make sure you aren't duplicating any work, but I don't think you are. go for it.

[jobala]

@raphaelokon

You can pick it up, I have been swamped with work.

Apologies for not updating you guys.

[raphaelokon]

Cheers. I will start with the fs doc work. Do we need separate issues for those chunk of work or are you cool with it to create a todo list right here?

[gibfahn]

TODO list here should be fine.

[raphaelokon]

Following docs need better param descriptions:

fs (doc/api/fs.md)

• [x] fs.access(path[, mode], callback)
• [x] fs.accessSync(path[, mode])
• [x] fs.appendFile(file, data[, options], callback)
• [x] fs.appendFileSync(file, data[, options])
• [x] fs.chmod(path, mode, callback)
• [x] fs.chmodSync(path, mode)
• [ ] fs.chown(path, uid, gid, callback)
• [ ] fs.chownSync(path, uid, gid)
• [ ] fs.close(fd, callback)
• [ ] fs.closeSync(fd)
• [ ] fs.createReadStream(path[, options])
• [ ] fs.existsSync(path)
• [ ] fs.fchmod(fd, mode, callback)
• [ ] fs.fchmodSync(fd, mode)
• [ ] fs.fchown(fd, uid, gid, callback)
• [ ] fs.fchownSync(fd, uid, gid)
• [ ] fs.fdatasync(fd, callback)
• [ ] fs.fdatasyncSync(fd)
• [ ] fs.fstat(fd, callback)
• [ ] fs.fstatSync(fd)
• [ ] fs.fsync(fd, callback)
• [ ] fs.fsyncSync(fd)
• [x] fs.ftruncate(fd, len, callback)
• [ ] fs.ftruncateSync(fd, len)
• [ ] fs.futimes(fd, atime, mtime, callback)
• [ ] fs.futimesSync(fd, atime, mtime)
• [ ] fs.lchmod(path, mode, callback)
• [ ] fs.lchmodSync(path, mode)
• [ ] fs.lchown(path, uid, gid, callback)
• [ ] fs.lchownSync(path, uid, gid)
• [ ] fs.link(existingPath, newPath, callback)
• [ ] fs.linkSync(existingPath, newPath)
• [ ] fs.lstat(path, callback)
• [ ] fs.lstatSync(path)
• [ ] fs.mkdir(path[, mode], callback)
• [ ] fs.mkdirSync(path[, mode])
• [x] fs.mkdtemp(prefix[, options], callback)
• [ ] fs.mkdtempSync(prefix[, options])
• [x] fs.open(path, flags[, mode], callback)
• [ ] fs.openSync(path, flags[, mode])
• [ ] fs.read(fd, buffer, offset, length, position, callback) (the parameter descriptions should be written in the parameter list instead)
• [ ] fs.readdir(path[, options], callback)
• [ ] fs.readdirSync(path[, options])
• [ ] fs.readlink(path[, options], callback)
• [ ] fs.readlinkSync(path[, options])
• [ ] fs.readSync(fd, buffer, offset, length, position)
• [ ] fs.rename(oldPath, newPath, callback)
• [ ] fs.renameSync(oldPath, newPath)
• [ ] fs.rmdir(path, callback)
• [ ] fs.rmdirSync(path)
• [ ] fs.stat(path, callback)
• [ ] fs.truncate(path, len, callback)
• [ ] fs.truncateSync(path, len)
• [ ] fs.unlink(path, callback)
• [ ] fs.unlinkSync(path)
• [ ] fs.utimes(path, atime, mtime, callback)
• [ ] fs.utimesSync(path, atime, mtime)

[addaleax]

Maybe /cc @ameliavoncat ?

[ameliavoncat]

Are you still working on this? 😃

[raphaelokon]

Hi @ameliavoncat – yeah, I was ill but am back on it.

~Just completing~ Completed the TODO list 🙃

Now on actually targeting the single items.

[matejkrajcovic]

@raphaelokon Hi! Do you work on this? Don't you mind if I start with a few functions?

[raphaelokon]

@matejkrajcovic Go for it :-)

[Trott]

@nodejs/documentation Is there a way to triage and unstall this?

[benhalverson]

@raphaelokon @Trott which ones in the above list are done?

[Sir-Turtle]

@raphaelokon you completed the todo list eh? What are the outstanding items? I'm looking to make my first contribution so let me know if you need help thanks.

[matejkrajcovic]

@benhalverson @Sir-Turtle I've added default values to all function signatures in fs module and I have open PR to add callback function signatures. Maybe you can add new examples how to use those functions or improve function signatures in other modules.

[mstallmo]

Is there any work left to be done on this? I would love to lend a hand if I can!

[juggernaut451]

@MylesBorins would like to help in this if something is left

[apapirovski]

As far as I can tell, all the fs function signatures have been updated. Beyond that, this is a bit vague and hard to act on for anyone stumbling upon the issue. As such I'm going to close this out. If anyone still thinks docs are lacking, feel free to open a new issue with specific examples so we can get the community to help us out.