crypto: fixing typo's in methods syntax

[khairnarsaurabh23]

Fixed some typo's in crypto docs.

[mscdex]

Those aren't typos. They are indicating that that parameter is completely optional. Placing the comma inside the brackets makes that more evident since you can completely remove the brackets and everything in between and still have a syntactically valid function signature.

[khairnarsaurabh23]

@mscdex Thanking you.

[Trott]

I think it reflects a UNIX-y man page format and this is not the first time folks have misunderstood it. I do wonder if we might be better off emulating MDN. They don't bother trying to specify the function signature this way. They just call it (for example) setTimeout() and then list out the parameter possibilities separately. See https://developer.mozilla.org/en-US/docs/Web/API/setTimeout for an example.

That may get unwieldy for situations where we have multiple signature possibilities for a single function. And it would be a huge change to our docs. There may be many downsides I haven't considered. So my suggestion here may be a terrible idea.

[richardlau]

We could do with a doc writing guide (#25548). At the moment it's kind of split between

• https://github.com/nodejs/node/blob/master/doc/guides/doc-style-guide.md
• https://github.com/nodejs/node/blob/master/tools/doc/README.md (where the example is actually the other way round and in line with what this PR was proposing -- i.e. not reflecting the actual common case).

That may get unwieldy for situations where we have multiple signature possibilities for a single function. And it would be a huge change to our docs. There may be many downsides I haven't considered. So my suggestion here may be a terrible idea.

FWIW there's discussions around adopting Electron's style guide (partly to make it easier to derive type information): #40953

[khairnarsaurabh23]

@mscdex can we write a note at top of the page or the pop up?