Repository navigation
Crypto docs don't explain the function signatures #12946
Description
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.
Activity
Trott commentedon May 10, 2017
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.doc: update doc of publicEncrypt method
doc: update doc of publicEncrypt method
stuartpb commentedon May 19, 2017
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 commentedon May 19, 2017
Ah, right. Sorry, reopening.
I think there is, we have something like
* Returns: {integer} The number of bytes contained within `string`for that.Clarified documentation for crypto.publicDecrypt() and similar functi…
doc: Clarified documentation for crypto.publicDecrypt() and similar f…
jieyanhuang commentedon Oct 14, 2017
Looks like the PR never got merged, does this still require attention? I can clean this up if help is still needed
joyeecheung commentedon Oct 15, 2017
@jieyanhuang Please do! Our contributing guide should provide enough guidance on how to sumbit a PR.
doc: clarify documentation in crypto
jieyanhuang commentedon Oct 16, 2017
@joyeecheung I've made a PR to address this. Let me know if I missed anything
doc: add return values in crypto documentation
doc: add return values in crypto documentation