New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
6 participants
@sstern6
Contributor

sstern6 commented Oct 11, 2016

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

doc/api/crypto.md Outdated
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()`.

This comment has been minimized.

@jasnell

jasnell Oct 11, 2016

Member

Nit: line wrap at 80 chars please :-)

This comment has been minimized.

@jasnell

jasnell Oct 11, 2016

Member

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

This comment has been minimized.

@sstern6

sstern6 Oct 11, 2016

Contributor

Will get on this, thanks for the feedback

This comment has been minimized.

@Trott

Trott Oct 11, 2016

Member

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.

This comment has been minimized.

@sstern6

sstern6 Oct 14, 2016

Contributor

@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

This comment has been minimized.

@Trott

Trott Oct 14, 2016

Member

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

This comment has been minimized.

@Trott

Trott Oct 14, 2016

Member

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

This comment has been minimized.

@sstern6

sstern6 Oct 14, 2016

Contributor

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

doc/api/crypto.md Outdated
@@ -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`.

This comment has been minimized.

@Trott

Trott Oct 11, 2016

Member

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.

doc/api/crypto.md Outdated
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()`.

This comment has been minimized.

@Trott

Trott Oct 11, 2016

Member

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

lpinca approved these changes Oct 12, 2016

LGTM with nits addressed.

@lpinca

This comment has been minimized.

Member

lpinca commented Oct 12, 2016

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

@sstern6

This comment has been minimized.

Contributor

sstern6 commented Oct 12, 2016

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

@sstern6 sstern6 force-pushed the sstern6:issue-9005 branch 2 times, most recently Oct 14, 2016

@jasnell

LGTM

doc/api/crypto.md Outdated
@@ -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,

This comment has been minimized.

@Trott

Trott Oct 14, 2016

Member

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

This comment has been minimized.

@sstern6

sstern6 Oct 14, 2016

Contributor

@Trott updated

@Trott

Trott approved these changes Oct 14, 2016

@sstern6

This comment has been minimized.

Contributor

sstern6 commented Oct 14, 2016

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

Thanks

@sstern6 sstern6 force-pushed the sstern6:issue-9005 branch to 34d4bfc Oct 14, 2016

@jasnell jasnell self-assigned this Oct 17, 2016

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

doc: update reference to list hash algorithms in crypto.md
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

This comment has been minimized.

Member

jasnell commented Oct 17, 2016

Landed in 3d294cf. Thank you!

@jasnell jasnell closed this Oct 17, 2016

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

doc: update reference to list hash algorithms in crypto.md
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 a commit that referenced this pull request Nov 11, 2016

doc: update reference to list hash algorithms in crypto.md
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 a commit that referenced this pull request Nov 11, 2016

doc: update reference to list hash algorithms in crypto.md
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>

This was referenced Nov 22, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment