tools/doc: improvements for types#11167
Conversation
silverwind
added
doc
|
The first commit LGTM. For the second, I would prefer a more generic syntax like |
|
I actually prefer primitives to stay lowercase. Can't we just fix the parser? Also on an unrelated note, in the particular example you showed, the inline 'pem' property description should actually have |
I don't have stats, but I estimate that > 80% of our types are currently capitalized.
That'd be quite hard to parse. It's not following the type convention of |
I'm not suggesting it should parse it necessarily, I'm mostly just pointing out a typo that should be corrected. |
tools/doc/type-parser.js
Outdated
There was a problem hiding this comment.
Can we merge this if...else chain with the previous one on line 57?
|
So on current master we have 571 occurences in docs with capitalized primitive types and 160 without. I could change those all to lowercase as suggested by @mscdex. MDN currently lists them capitalized and the |
I would consider this as a problem. |
silverwind
force-pushed
the
doc-types
branch
from
2189a90 to
e8409ac
Compare
|
Updated:
Example:
@nodejs/documentation PTAL. |
|
Consistency sounds great to me. Is the example in #11167 (comment) what it looks like now? How come |
|
Because |
|
@silverwind, have you seen my comment above? |
|
Yes, I think |
|
Not so sure that's a useful distinction that we need to convey to our doc readers, given that strings do have methods in practical cases, but at least its something we can point to in our docs, and say we are following jsdoc. Did you mean to write |
|
BTW flow and TypeScript are using lower-cased primitive types too(therefore used by definitely typed, where a lot of people get their types from in their tools nowadays even if they don't use TypeScript) |
|
FWIW, Tern also uses lowercased primitive types. |
|
My mind is trained to understand a name as a constructor function if it starts with a capital letter. So I am going to go with lowercase names. |
|
I think we are in agreement that lowercase primitives is the way to go. Can I get a few LGTMs? I'll rebase and land shortly after it's approved. |
PR-URL: #11167 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
|
ping |
|
Backport in #13054 |
PR-URL: #11167 Backport-PR-URL: #13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: #11167 Backport-PR-URL: #13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: #11167 Backport-PR-URL: #13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: #11167 Backport-PR-URL: #13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: nodejs#11167 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: nodejs#11167 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: nodejs#11167 Backport-PR-URL: nodejs#13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: nodejs#11167 Backport-PR-URL: nodejs#13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: #11167 Backport-PR-URL: #13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: #11167 Backport-PR-URL: #13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: #11167 Backport-PR-URL: #13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
PR-URL: #11167 Backport-PR-URL: #13054 Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
11 participants
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passesAffected core subsystem(s)
The first commit capitalizes all primitive types so the parser can pick them up.
The second commit adds logic to the doctool to allow parsing of
Type[]array syntax.Before
After