tools/doc: improvements for types

[silverwind]

Checklist

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

Affected 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

[TimothyGu]

The first commit LGTM. For the second, I would prefer a more generic syntax like Array<String>. This way, we can not only have links to MDN for both Array and String, but also have better symmetry with other language types/protocols like Promise and Iterable (e.g. for URLSearchParams it'd be Iterable<String, String>).

[mscdex]

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 Buffer instead of buffer too.

[silverwind]

I actually prefer primitives to stay lowercase

I don't have stats, but I estimate that > 80% of our types are currently capitalized.

the inline 'pem' property description should actually have Buffer instead of buffer too.

That'd be quite hard to parse. It's not following the type convention of {Type} at all.

[mscdex]

That'd be quite hard to parse. It's not following the type convention of {Type} at all.

I'm not suggesting it should parse it necessarily, I'm mostly just pointing out a typo that should be corrected.

[lpinca]

Can we merge this if...else chain with the previous one on line 57?

[silverwind]

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 href would need to be capitalized as well.

[thefourtheye]

... the href would need to be capitalized as well.

I would consider this as a problem.

[silverwind]

Updated:

• Primitive types are now all lowercased. This seems to be a common convention in JS documention.
• Removed some duplicated code as per @lpinca's suggestion and made sure primitives of any case are picked up correctly by the parser.

Example:

@nodejs/documentation PTAL.

[sam-github]

Consistency sounds great to me.

Is the example in #11167 (comment) what it looks like now?

How come string is lower case, and Buffer and Object are upper case? It seems a bit random. Its not even built-in vs node specific, because String and Object are both builtin.

[silverwind]

Because stringis a primitive while the others are not.

[TimothyGu]

@silverwind, have you seen my comment above?
#11167 (comment)

[silverwind]

Yes, I think Array<String> make sense for non-Array types, and it's certainly something we can support in the parser. I'd just like to avoid packing too many changes in this PR. Maybe open an separate issue for it?

[silverwind]

While I couldn't find definitive recommendations, the style of lowercasing primitives (and capitalizing everything else) is in use by both JSDoc and closure compile. See examples here and here.

[sam-github]

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 Array<String> , not Array<string>?

[joyeecheung]

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)

[TimothyGu]

FWIW, Tern also uses lowercased primitive types.

[thefourtheye]

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.

[silverwind]

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.

[joyeecheung]

LTGM with a rebase

[silverwind]

Thanks! Rebased and landed in ff13619 and 9be03a2.

[MylesBorins]

ping

[silverwind]

Backport in #13054