Return value of fs.unlinkSync not documented

[binarykitchen]

Somehow http://nodejs.org/api/fs.html#fs_fs_unlinksync_path does not tell what it's return value is. I'd like to know it. Would be good to add this on that page.

Thanks!

[cjihrig]

I don't think it returns anything (undefined). I personally think it would be useful if the return value of every method was documented, even when it's undefined, I'm not sure if everyone else would like that. Also, are you volunteering to do the potential docs work?

[binarykitchen]

Well IMO those developers who have been working on fs should document it. It's a bad idea if someone else, who never dealt with fs, like me, is documenting it.

All I want to know what happens when unlinkSync() fails to perform due to invalid permissions? Will it throw an exception or just return false?

[cjihrig]

Well IMO those developers who have been working on fs should document it. It's a bad idea if someone else, who never dealt with fs, like me, is documenting it.

You're right. Unfortunately, the documentation is what it is, and help is welcome.

All I want to know what happens when unlinkSync() fails to perform due to invalid permissions? Will it throw an exception or just return false?

An exception is thrown. In most cases, if an error would be passed to an asynchronous callback, it translates into a thrown exception in synchronous code.

[misterdjules]

@binarykitchen @cjihrig We could make the introduction to http://nodejs.org/api/fs.html clearer by mentioning that the return value of synchronous versions is undefined, and that the way this API communicates errors is via exceptions that must be caught to be handled.

What do you think?

[binarykitchen]

@misterdjules Perfect. But make sure to highlight it.

@cjihrig How about adding a policy enforcing every developer to update the documentation whenever they modify the API?

[misterdjules]

Ok, reopening this issue and added the easy label so that someone can pick it up as a first contribution.

[cjihrig]

@binarykitchen such a policy exists. It probably always existed. Sometimes things just slip through the cracks. I'm not trying to make any excuses for the docs though.

[tyleranton]

I'd like to take this if it's still up for grabs. It'd be my first contribution.

[misterdjules]

@tyleranton That's great!

Please not however that I do not agree anymore with what I said in my previous comment :)

Basically, I think that instead of mentioning in the introduction that "all functions for which the returned value is not mentioned return undefined", I think we sould mention the return value in each function's documentation section.

The reason for that is that users can jump to specific functions in the documentation without reading the introduction (it's an API documentation, not a tutorial), and thus they would miss this information.

So my suggestion would be, depending on the time you have, to either just fix the documentation for fs.unlinkSync by adding that it returns undefined, or if you have more time to fix that for every synchronous function of the fs module that returns undefined.

Does that make sense? @joyent/node-coreteam What do you think?

If you need help with any of this, I can help you in #libuv on Freenode (my nickname is jgi), or here on GitHub.

Thank you!

[tyleranton]

@misterdjules I'd be more than glad to update each function's doc. I'm assuming the change needs to made in both the nodejs website AND the fs.markdown in nodejs?

As for verbiage, is "Returns undefined." sufficient?

Thanks!

[misterdjules]

@tyleranton Excellent, thank you! The change actually needs to be made only in nodejs. For each new release, the docs are generated from node's repository and deployed to the nodejs.org website.

To test your changes to the documentation, you can run make doc and open out/doc/api/index.html.

"Returns undefined." is good, but we will probably want to format "undefined" as code with undefined.