doc: correctly reference where to list hash algorithms.

[sstern6]

Checklist

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

Affected core subsystem(s)

Docs.

Description of change

Fixes Issue: #9005.

Update crypto docs by removing inaccurate command explanation from crypto.createSign(algorithm) and crypto.createVerify(algorithm),
accurately referencing how to get available hash algorithms from crypto.getHashes().

[jasnell]

Needs a few cleanups

[jasnell]

Nit: line wrap at 80 chars please :-)

[jasnell]

If we go with this approach, it would be best to make crypto.getHashes() a link to the right location.

[sstern6]

Will get on this, thanks for the feedback

[Trott]

Using reference makes it sound like you should refer to the documentation for crypto.getHashes() but what is really meant is to run it to obtain the array of available algorithms, right? If so, instead of this:

For available signing algorithms, please reference crypto.getHashes().

...I'd prefer something like:

Use [crypto.getHashes()][] to obtain an array of names of the available signing algorithms.

[sstern6]

@jasnell for linking to crypto.getHashes() would you reccomend putting a <a id="getHashes"></a> above crypto.getHashes() in the markdown, or do you have another preferred method?

Thanks

[Trott]

@sstern6 The linking is done via markdown. @jasnell is basically saying instead of using this markdown:

`crypto.getHashes()`

...use this markdown instead:

[`crypto.getHashes()`][]

Then make sure that the link is specified in the list of links at the bottom of the markdown document.

[Trott]

@sstern6 Some more info: That linking style is used throughout the doc and all (or nearly all) our other API docs. You can read about it at https://daringfireball.net/projects/markdown/syntax#link if you search for implicit link name shortcut.

[sstern6]

thanks @Trott getting to that now. The link is already declared at the bottom of the page.

Updating the PR with all of the comments

[Trott]

The added text is a sentence fragment (which is fine for the first "sentence", but subsequent statements should be complete sentences). It seems unnecessary anyway. If we do want to include the example, I'd prefer:

Returns an array with the names of the supported hash algorithms, such as RSA-SHA256.

[Trott]

Using reference makes it sound like you should refer to the documentation for crypto.getHashes() but what is really meant is to run it to obtain the array of available algorithms, right? If so, instead of this:

For available signing algorithms, please reference crypto.getHashes().

...I'd prefer something like:

Use [crypto.getHashes()][] to obtain an array of names of the available signing algorithms.

[lpinca]

LGTM with nits addressed.

[lpinca]

@sstern6 can you please adjust the commit message to make it follow the guidelines? Thank you.

[sstern6]

Thanks everyone, will have all of these addressed by end of day.

[jasnell]

LGTM

[Trott]

Micro-nit: array with the names -> array of the names

[sstern6]

@Trott updated

[sstern6]

@Trott will have the micronit fixed by 4:30pst today.

Thanks

[jasnell]

Landed in 3d294cf. Thank you!