CODEWITHSUNDEEP
javascriptnode.js
Pompey Magnus
Pompey Magnus

Reputation: 2341

Trying to understand nodejs documentation. How to discover callback parameters

When I read this Node.js API docs, it raises a few questions for me.

  1. In this particular case, is the example they use the only thing that tells me that the 1 parameter in the callback is 'err'?
  2. Going forward do I assume that there is only the 'err' parameter in the callback unless otherwise noted?
  3. Seems to me to me the callback parameters should be listed in a common pattern, like here: "callback <Function>" in the header. Why am I wrong in that thinking?

Upvotes: 3

Views: 93

Answers (2)

slebetman
slebetman

Reputation: 113926

In general the arguments to callbacks are always documented for each function. However, in cases where the callback does not have any arguments they will not be mentioned at all.

On the other hand, the first arguments for callbacks are reserved for errors (because async functions cannot throw errors properly otherwise). Therefore if a callback expects no arguments then the only argument it should expect is an error.

So the documentation generally:

  1. Documents arguments to callbacks.

  2. Does not mention anything if the only argument to the callback is an error (this implies that the callback produces no useful value).

  3. Documents all cases where callbacks deviates from either of the above (either has no arguments at all or does not have an error argument).

So in the specific case you mention. Yes, the example is correct. Errors are the only arguments to the callback for that function - hence no mention is made to callback arguments.

Upvotes: 1

Amadan
Amadan

Reputation: 198344

Documentation on fs:

The asynchronous form always takes a completion callback as its last argument. The arguments passed to the completion callback depend on the method, but the first argument is always reserved for an exception. If the operation was completed successfully, then the first argument will be null or undefined.

So, yes, assume callback to fs methods to have signature (err) unless noted otherwise. You should not assume this to be the signature of other packages, unless it is noted similarly.

Is there a standard doc producing tool like javadoc in javascript?

What options are available for documenting your Javascript code?

Upvotes: 1

Related Questions