Standardize readme type notation

[sindresorhus]

I would like to standardize the type notation I use in my API docs. Currently I'm using string, array, etc, but I have no consistent notation for a collection of values and I use buffer, which is clearly wrong as the type is Buffer.

Example: https://github.com/sindresorhus/boxen#borderstyle

I would like to figure out a good convention for this.

My proposal is to follow the Facebook Flow types as close a practical.

One thing I don't like with the Flow types is that primitives are lowercase. While this makes sense in typing, it looks very ugly in API docs:

Type: `string` `Array`

I propose we make an exception and also PascalCase primitives.

We also need a notation for nested types. For example an Array of booleans or a Set of strings.

TypeScript (and Java) seems to use string[] for an array of strings. While Facebook Flow uses Array<string>. The TypeScript notation looks better individually, but imagine if you want to notate a Set of strings, it would be Set<string> which makes string[] inconsistent and not that clear.

I propose we stick with the Facebook Flow notation of always notating the collection type. So it would be Array<String> and Set<String>. Thoughts?

If an Array can contain multiple types. Should we use separate notations Array<String> Array<Boolean> or Array<Boolean | String>?

// @SamVerschueren @jamestalmage @kevva @vdemedes @passy @novemberborn

[vadimdemedes]

All conventions sound good to me. string[] reminds me of C, so Set<String> would be much better.

As for the last one:

Should we use separate notations Array Array or Array<Boolean | String>?

I'm voting for Array<Boolean | String>, as it saves space and pretty self-explanatory with | (or).

[SamVerschueren]

I propose we make an exception and also PascalCase primitives.

But there is a difference between boolean and Boolean for instance. The primitive boolean notation indicates true or false while Boolean indicates the Boolean object.

One thing I don't like with the Flow types is that primitives are lowercase. While this makes sense in typing, it looks very ugly in API docs

That's true, but the API docs should be correct as to what it returns. If we write Number, devs might think it returns a Number object which isn't 100% correct.

---

About the Array<string> Vs. string[] notation. I don't have a strong opinion for either one of these, but I might have a slight favour for the short-hand notation though. If we declare an array of numbers, we are aways writing [1, 2] instead of new Array(1, 2). Because it's much shorter and it's clear to everyone that's an array. Now we have more collection types like Map, Set, etc. They don't have a shorthand notation and require you to write new Map() in order to instantiate a new map.

So these are some examples that I might use in documentation

• string
• string[]
• Map<string, string> (Map has a key and a value that needs to be specified)
• Map<number, string[]>
• Set<string>

I feel Map<number, string[]> is more readable then Map<number, Array<string>>.

But if we really want to go for consistency, we should use the Array<string> notation.

[Qix-]

So some things I'm seeing are not very Javascript-y.

One must look at the practicality of basic types, for example. Nobody uses boxed types. That's the reality of it. If you're using boxed types, there's usually another way of doing it - especially at the API level.

As far as collections go, I agree with the sentiment that type[] is very C-like in nature. However, so are Map<type, type>, Set<type>, etc.

It seems such declarations are trying to make things look a lot like code and a lot less like human-readable documentation. While I understand the need for such a standardization to be regular so it can be parsed automatically, it should still be parsable manually.

One thing to mention, as someone who finds verbosity in, say, Java a little overwhelming at times, is when you need to nest collections. What about nests of nests? What about an unbalanced nesting?

Map<string, Map<string, Set<Map<number, string>>>> is unreadable to me, in part by the parens. Plus, none of that looks like Javascript.

There are other things to consider here as well. Optional/multi-type arguments, weak contract types (i.e. something that is an Array.isArray(...) === true, or something that is like an array, e.g. pseudoArray[0].

Yet another consideration is to show the intent of the object. Since Javascript is prototypical and allows for some very clever hacks, if we show how the value is to be used, the consuming library can make the we're-all-consenting-adults-here decision to (mis)use it in such a way that works for them. That's one of the beauties of dynamically typed languages, and why Javascript is seen as powerful in the first place.

The best part is, if the consuming library is misusing a type that has been well-defined insofar as the intent, the repository owner doesn't have to support it and can give clear reasons as to why (i.e. the docs tell you exactly how it's supposed to be used). We can't control downstream consumers, so we might as well protect ourselves with docs.

---

At the very least, I highly suggest we keep with Javascript object notation for plain objects.

Type: {string: number}
Type: {string: {number: boolean}}

is much easier to read and understand than

Type: Map<string, number>

---

Further, I am throwing my hat in the ring for wrapping array types with square brackets (though I do not have a strong opinion on this either way).

Type: [string]
Type: [{number: boolean}]

---

As for multiple acceptable types, a simple | should do.

Type: string|number
Type: {string: number|boolean}

---

When it comes to constant values, those should be capitalized. Since, as I suggested earlier, boxed types shouldn't be used at an API level, this makes constant values completely discernible.

Type: number|False
Type: {string: boolean|Null}

---

If the function is going to be using the passed array in a way that requires a real array, I think it should be denoted as such. On the contrary, if we want to imply all arrays are to be strict (i.e. Array.isArray(...) === true then we should denote when they can be loose arrays - however I highly urge for the former due to the fact we use subscripts more than methods (this is arguable).

Type: Array(string)

or

Type: [strict string]

or

Type: string[strict]

or something to that effect - depending on how the syntax is formulated.

---

When it comes to sets (which I don't personally believe warrant their own 'primitive' type in this documentation), we could follow suit to strict arrays:

Type: Set(string) // hate this...

or

Type: [unique string]

or

Type: string[unique]

and bonus points for combining them (can't really do it with the first example from above):

Type: [unique strict string]

or

Type: string[unique strict]

---

Another alternative for collections would be slightly more cryptic but more terse - in that you'd have to know what you're looking for. For most cases this is innocuous as most developers tend to know when they're passing a pseudo array when they should be passing a real array given an inevitable error.

However, to document it better, we could be using ellipsis to show collections and use angle brackets to denote strict array requirements.

Type: string...
Type: <string...>

There a few benefits to this approach:

• ellipsis are extremely clear and a very well defined pattern
• < ... > is otherwise invalid syntax in javascript, which should signal to the astute reader that they mean something of importance in a documentation context
• < ... > in most other places denote 'required', although normally in a quantitive meaning, not a qualitative.
• at least to me, < type... > is much less confusing, if at all, to [ type ], since the latter may be confused as 'optional'/
• they work well with nesting (see next example)

Type: {string: string...}
Type: {string: <string...>}

---

Just some thoughts. The goal here is to be readable and clear for both correctness as well as intent. I think pulling in features of other languages just to describe this language is a bit foolish. Javascript isn't type safe and will never be type safe, and trying to box it into being type safe, in my opinion, is a cause for writing less than hardy code (at least as far as Node.js goes).

[SamVerschueren]

That's quite some content to process :). My first remark I have is regarding this piece

At the very least, I highly suggest we keep with Javascript object notation for plain objects.

Type: {string: number}
Type: {string: {number: boolean}}

is much easier to read and understand than

Type: Map<string, number>

You might be right that it's much easier to reason about, but we're talking about an ES6 Map type here. That's far from equivalent to {string: number}. If you see {string: number}, you might think you can access properties with the dot-notation. If it's map, that's not possible and you have to do .get(key) to accomplish that.

[passy]

I'm not a fan of annotations that cannot be statically verified. With the default PureScript tooling for example, you get your type docs automatically generated and updated on every build.

But in any case I'd avoid creating another standard to document types. With TypeScript you could keep your "typings" separate and have a clear, standardized syntax for describing them. What about that approach?

[jamestalmage]

I don't have time to react to everything said here (hopefully later today). But a few quick thoughts:

• prefer <Type> over {Type} - I've never seen the latter used, and it looks like destructuring.
• Array<String> | Array<Number> means an Array of Strings or an Array of Numbers. Array<String | Number> means a mixed Array of Strings and/or numbers.
• Some of the Babel docs contain Flow interface declarations for defining different structs. My recollection is that it was helpful, and I've never read any Flow documentation.

[developit]

Also worth mentioning that documentation.js / esdoc both seem to favor Array<String>

[SamVerschueren]

Found this in the esdoc documentation

/**
 * @param {number[]} param - this is array param.
 */
function myFunc(param){...}

[Jameskmonger]

@sindresorhus Sorry to jump in here!

• An object with type Array<string> | Array<boolean> is either an array entirely containing string or booleans.
• An object with type Array<string | boolean> is an array which can contain both string and booleans.

So to answer your question "If an Array can contain multiple types", you would want to use Array<string | boolean>.

[sindresorhus]

Note to self: I'm just gonna use TypeScript notation. That means all primitives are lowercase and non-primitives are pascal-case.

In addition, I'm gonna start using Type: `object instead of Type: `Object for consistency with TS. So object is the exception to the above rule. (Relevant sindresorhus/indent-string#16 (comment)).

And foo([options]) => foo(options?)

[sindresorhus]

Slightly related, I'm going to start using \ for line breaks instead of <br>. \ is supported by the latest CommonMark spec and GitHub.

[fregante]

Aren’t linebreaks added with double spaces at the end of a line?

[SamVerschueren]

Not possible with trim trailing whitespace set :)

[sindresorhus]

@fregante I used to use double-spaces, people kept stripping them in pull requests. Double-spaces was a horrible idea anyway. Glad we have \ now.