doc: correctly reference where to list hash algorithms. #9043

sstern6 · 2016-10-11T23:29:54Z

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 · 2016-10-11T23:38:59Z

doc/api/crypto.md

-Creates and returns a `Sign` object that uses the given `algorithm`. On
-recent OpenSSL releases, `openssl list-public-key-algorithms` will
-display the available signing algorithms. One example is `'RSA-SHA256'`.
+Creates and returns a `Sign` object that uses the given `algorithm`. For available signing algorithms, please reference `crypto.getHashes()`.


Nit: line wrap at 80 chars please :-)

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

Will get on this, thanks for the feedback

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.

@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

@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.

@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.

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 · 2016-10-11T23:51:41Z

doc/api/crypto.md

@@ -1320,7 +1316,7 @@ console.log(alice_secret == bob_secret);
 added: v0.9.3
 -->

-Returns an array with the names of the supported hash algorithms.
+Returns an array with the names of the supported hash algorithms. For example, `RSA-SHA256`.


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 · 2016-10-11T23:56:19Z

doc/api/crypto.md

-Creates and returns a `Sign` object that uses the given `algorithm`. On
-recent OpenSSL releases, `openssl list-public-key-algorithms` will
-display the available signing algorithms. One example is `'RSA-SHA256'`.
+Creates and returns a `Sign` object that uses the given `algorithm`. For available signing algorithms, please reference `crypto.getHashes()`.


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 · 2016-10-12T17:35:09Z

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

sstern6 · 2016-10-12T17:36:59Z

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

jasnell

LGTM

Trott · 2016-10-14T21:26:04Z

doc/api/crypto.md

@@ -1320,7 +1320,8 @@ console.log(alice_secret == bob_secret);
 added: v0.9.3
 -->

-Returns an array with the names of the supported hash algorithms.
+Returns an array with the names of the supported hash algorithms,


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

@Trott updated

sstern6 · 2016-10-14T21:46:12Z

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

Thanks

PR-URL: #9043 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

jasnell · 2016-10-17T15:56:13Z

Landed in 3d294cf. Thank you!

PR-URL: #9043 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

nodejs-github-bot added crypto Issues and PRs related to the crypto subsystem. doc Issues and PRs related to the documentations. labels Oct 11, 2016

jasnell requested changes Oct 11, 2016

View reviewed changes

Trott requested changes Oct 11, 2016

View reviewed changes

lpinca approved these changes Oct 12, 2016

View reviewed changes

sstern6 force-pushed the issue-9005 branch 2 times, most recently from 287e57d to 09162f8 Compare October 14, 2016 04:42

jasnell approved these changes Oct 14, 2016

View reviewed changes

Trott reviewed Oct 14, 2016

View reviewed changes

Trott approved these changes Oct 14, 2016

View reviewed changes

doc: update reference of where to list hash algorithms in crypto.md.

34d4bfc

sstern6 force-pushed the issue-9005 branch from 09162f8 to 34d4bfc Compare October 14, 2016 22:44

jasnell self-assigned this Oct 17, 2016

jasnell pushed a commit that referenced this pull request Oct 17, 2016

doc: update reference to list hash algorithms in crypto.md

3d294cf

PR-URL: #9043 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

jasnell closed this Oct 17, 2016

jasnell pushed a commit that referenced this pull request Oct 17, 2016

doc: update reference to list hash algorithms in crypto.md

0022bfe

PR-URL: #9043 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

MylesBorins pushed a commit that referenced this pull request Nov 11, 2016

doc: update reference to list hash algorithms in crypto.md

68ccc7a

PR-URL: #9043 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

MylesBorins pushed a commit that referenced this pull request Nov 11, 2016

doc: update reference to list hash algorithms in crypto.md

de2f050

PR-URL: #9043 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

MylesBorins added land-on-v4.x labels Nov 11, 2016

This was referenced Nov 22, 2016

v6.9.2 proposal #9735

Merged

v4.7.0 proposal #9736

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: correctly reference where to list hash algorithms. #9043

doc: correctly reference where to list hash algorithms. #9043

sstern6 commented Oct 11, 2016 •

edited

jasnell left a comment

jasnell Oct 11, 2016

jasnell Oct 11, 2016

sstern6 Oct 11, 2016

Trott Oct 11, 2016

sstern6 Oct 14, 2016

Trott Oct 14, 2016

Trott Oct 14, 2016

sstern6 Oct 14, 2016

Trott Oct 11, 2016

Trott Oct 11, 2016

lpinca left a comment

lpinca commented Oct 12, 2016 •

edited

sstern6 commented Oct 12, 2016

jasnell left a comment

Trott Oct 14, 2016

sstern6 Oct 14, 2016

sstern6 commented Oct 14, 2016

jasnell commented Oct 17, 2016

doc: correctly reference where to list hash algorithms. #9043

doc: correctly reference where to list hash algorithms. #9043

Conversation

sstern6 commented Oct 11, 2016 • edited

Checklist

Affected core subsystem(s)

Description of change

jasnell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lpinca left a comment

Choose a reason for hiding this comment

lpinca commented Oct 12, 2016 • edited

sstern6 commented Oct 12, 2016

jasnell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sstern6 commented Oct 14, 2016

jasnell commented Oct 17, 2016

sstern6 commented Oct 11, 2016 •

edited

lpinca commented Oct 12, 2016 •

edited