Crypto docs don't explain the function signatures

[stuartpb]

I just spent about an hour bashing my head against the wall because the documentation for crypto.publicEncrypt & co. don't explain that they return a new Buffer with the encrypted data instead of encrypting the passed-in Buffer in place.

Yes, in hindsight, this should have been obvious, but I don't get why these functions don't explain their return values when so much of the rest of core does.

[Trott]

Thanks for reporting this. If you or someone else wants to update the documentation and submit a pull request, the markdown file containing the relevant documentation is doc/api/crypto.md.

[stuartpb]

Okay, that fixes the documentation for publicEncrypt, but it doesn't touch the documentation for the other three functions like it (and I'd expect that there are more ambiguities like this in the docs right now).

Also, isn't there a formal way of documenting a function's return type?

[addaleax]

Ah, right. Sorry, reopening.

Also, isn't there a formal way of documenting a function's return type?

I think there is, we have something like * Returns: {integer} The number of bytes contained within `string` for that.

[jieyanhuang]

Looks like the PR never got merged, does this still require attention? I can clean this up if help is still needed

[joyeecheung]

@jieyanhuang Please do! Our contributing guide should provide enough guidance on how to sumbit a PR.

[jieyanhuang]

@joyeecheung I've made a PR to address this. Let me know if I missed anything