doc: clarified documentation for crypto.publicEncrypt() and similar functions

[WilliamT1]

Fixes: #12946

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

[mscdex]

I think if we're going to convert at least one document, it should be done for all functions and not just a select few. Also, the format for documenting the return value isn't quite in line with that of other built-in module docs (for example some of the methods in the buffer documentation).

[refack]

@WilliamT1 Thank you for your contribution 🥇 and welcome 🎉
I've made some edits to your title and first comment (moved the reference to the 12946 issue) so it'll use GitHub cross reference feature (since issue numbers are ignored in titles).

As you see, once you open a PR the other contributors will give you comments. That our way to make sure that your contribution brings the maximal benefit to the codebase. It's all covered in our CONTRIBUTING.md guide.

For this PR you should adjust the commit message (as per step 3 in the guide), then you can check the box in the first comment.
Also you should consider following @mscdex's comment and, first adjest the format of the changes you made to fit the other examples in the file (like for example the signature of certificate.exportChallenge), and then maybe have a go at documenting the rest of the functions 👍

Good luck and thank you again.

[refack]

Linter CI: https://ci.nodejs.org/job/node-test-linter/9533/

[refack]

@WilliamT1 are you interested in following up on the reviews?

[BridgeAR]

There was no update on this for a long time. Closing therefore.

@WilliamT1 thanks a lot for your contribution anyway and if you would like to follow up on this, please feel free to reopen!