doc: link and style parameter types #4741

claudiorodriguez · 2016-01-18T12:39:37Z

Changes the parsing of parameter types, links to MDN or
nodejs docs. See #4350

Replaces PR #4378

claudiorodriguez · 2016-01-18T12:42:46Z

@jasnell Remade the PR fresh off master to make sure everything is clean, since this touches a bunch of docs the merging may produce some conflicts for other open PRs, but they should be minor

jasnell · 2016-01-18T16:39:49Z

LGTM
@nodejs/documentation

jasnell · 2016-01-18T16:40:17Z

Thank you @fansworld-claudio!

cjihrig · 2016-01-18T17:10:23Z

LGTM, but I'll defer to the docs team.

thefourtheye · 2016-01-18T17:15:21Z

doc/api/crypto.markdown

@@ -666,8 +666,8 @@ The `private_key` argument can be an object or a string. If `private_key` is a
 string, it is treated as a raw key with no passphrase. If `private_key` is an
 object, it is interpreted as a hash containing two properties:

-* `key` : A string holding the PEM encoded private key
-* `passphrase` : A string of passphrase for the private key
+* `key` : {String} - PEM encoded private key


Other places didn't have colons.

Also, it would be better if the type and description seperator is consistent in all the files.

@thefourtheye I agree, but unfortunately everything was already inconsistent. I think refactoring that belongs to another PR IMHO

Fair enough.

Yeah, there are quite a few areas here where incremental improvements need to be made. We'll get there but breaking it up into smaller incremental changes is likely best

@jasnell Yup, I completely agree. That would be much easier to review as well :)

thefourtheye · 2016-01-18T18:06:37Z

LGTM and Thanks a lot @fansworld-claudio :-)

Fishrock123 · 2016-01-18T18:13:03Z

doc/api/child_process.markdown

@@ -641,7 +641,7 @@ See `waitpid(2)`.
 ### Event: 'message'

 * `message` {Object} a parsed JSON object or primitive value.
-* `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or
+* `sendHandle` {Handle} a [`net.Socket`][] or [`net.Server`][] object, or


This link does not appear to work.

Fishrock123 · 2016-01-18T18:13:23Z

I like this. In any case it's a step forward.

Fishrock123 · 2016-01-18T18:14:32Z

tools/doc/type-parser.js

+];
+const typeMap = {
+  'Buffer': 'buffer.html#buffer_class_buffer',
+  'Handle': 'net.html#net_server_listen_handle_callback',


Handle probably needs to be more specific, there are many types of handles, although they all inherit from AsyncWrap afaik.

@Fishrock123 I'm a bit out of my depth there. I'm fixing the link, but no idea where to link to exactly other than that.

chrisdickinson · 2016-01-19T03:12:04Z

This is excellent work! LGTM.

thefourtheye · 2016-01-19T03:35:51Z

I think it would be better if the tools part and the doc part are in different commits.

claudiorodriguez · 2016-01-19T14:13:30Z

Corrected a couple of things noted, thanks everyone. @thefourtheye you mean two commits in a single PR, or two separate PRs? I could do any of the two, if the current contents of the PR are okay

thefourtheye · 2016-01-19T15:34:35Z

@fansworld-claudio Given the fact that it has been reviewed by quite a few collaborators and owners, I would say splitting into two commits in this PR itself would be better.

claudiorodriguez · 2016-01-19T16:06:45Z

@thefourtheye is something like this alright?

thefourtheye · 2016-01-19T16:11:05Z

@fansworld-claudio Yup! :-)

silverwind · 2016-02-04T18:35:27Z

The buffer part of this was landed recently in 6ad1f7b. @fansworld-claudio could you update this PR?

claudiorodriguez · 2016-02-04T23:46:20Z

@silverwind That should do it, I think

jasnell · 2016-02-07T20:18:05Z

LGTM

silverwind · 2016-02-08T17:39:49Z

LGTM. @fansworld-claudio can you rebase once more?

claudiorodriguez · 2016-02-08T20:20:30Z

@silverwind Done

Changes the parsing of parameter types in the doc html gen Links to either MDN or nodejs docs depending on type See nodejs#4350

Fixes several type references in the docs so that the doc html gen tool that parses them can put the correct links in. Changes css styling for the generated type links.

Changes the parsing of parameter types in the doc html gen Links to either MDN or nodejs docs depending on type See #4350 PR-URL: #4741 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Chris Dickinson <chris@neversaw.us> Reviewed-By: Roman Reiss <me@silverwind.io>

Fixes several type references in the docs so that the doc html gen tool that parses them can put the correct links in. Changes css styling for the generated type links. PR-URL: #4741 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Chris Dickinson <chris@neversaw.us> Reviewed-By: Roman Reiss <me@silverwind.io>

silverwind · 2016-02-09T12:13:22Z

Thanks! Landed in e517efa and 47e926a.

Trott · 2016-02-09T17:35:31Z

This change does not lint cleanly with the current linting rules. I'll submit a PR to fix.

Refs: nodejs#4741 (comment)

silverwind · 2016-02-09T17:38:34Z

Whoops, thanks for picking up the slack @Trott.