"About Types" page based on @type #180
Conversation
|
Friendly ping. |
| @@ -0,0 +1,261 @@ | |||
| --- | |||
| title: Types | |||
There was a problem hiding this comment.
You'll need to do two more things so that this page actually shows up on the website:
- Add the page to an appropriate place in
data/toc.json. - Run
gulpto rebuild the HTML files for the website.
content/en/about-types.md
Outdated
| are specified with the [`@type` tag][type-tag], the [`@param` tag][param-tag], and many others. | ||
|
|
||
| [type-tag]: tags-type.html | ||
| [param-tag]: tags-param.html. |
content/en/about-types.md
Outdated
| [Google Closure Compiler type expression][closure], as well as several other formats that are | ||
| specific to JSDoc. | ||
|
|
||
| If JSDoc determines that a type expression is invalid, it will display an error and stop running. |
There was a problem hiding this comment.
Not your fault, but this paragraph is no longer accurate. It should say something more like:
If JSDoc determines that a type expression is invalid, it will display an error message. To force JSDoc to stop running when a type expression is invalid, use the --pedantic option.
content/en/about-types.md
Outdated
| <td> | ||
| <p> | ||
| This means a value can have one of several types, with the entire list of types enclosed in | ||
| parentheses and separated by <code>|</code>. The parentheses are required for Closure Compiler, |
There was a problem hiding this comment.
Is this accurate? I thought Closure Compiler supported type unions without parentheses, even though that behavior isn't documented.
There was a problem hiding this comment.
This doc says that they're required, but we then ignore that rule most other places. So you're right, I'll make it clear that they're optional by saying Closure "suggests" them.
content/en/about-types.md
Outdated
| </code></pre> | ||
| {% endexample %} | ||
|
|
||
| {% example "An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type)." %} |
There was a problem hiding this comment.
nit: comma after "(a string)"
content/en/about-types.md
Outdated
| </p> | ||
| <p> | ||
| For objects that have a known set of properties, you can use Closure Compiler's syntax for | ||
| documenting record types. You can document each property individually, which enables you to |
There was a problem hiding this comment.
s/You/As an alternative, you/
content/en/about-types.md
Outdated
| </td> | ||
| <td> | ||
| <p> | ||
| Document a callback using the <a href="tags-callback.html">@callback</a> tag. The syntax is |
There was a problem hiding this comment.
enclose tag name in <code>
content/en/about-types.md
Outdated
| <td> | ||
| <p> | ||
| Document a callback using the <a href="tags-callback.html">@callback</a> tag. The syntax is | ||
| identical to the @typedef tag, except that a callback's type is always "function." |
There was a problem hiding this comment.
enclose tag name in <code>, and change "function." to <code>function</code>.
content/en/tags-type.md
Outdated
| may contain, or the type of value returned by a function. You can also include type expressions with | ||
| many other JSDoc tags, such as the [@param tag][param-tag]. | ||
| The `@type` tag allows you to provide a type expression identifying the type of value that a symbol | ||
| may contain, or inline to indicate that a symbol is of a specific type. |
There was a problem hiding this comment.
I found this confusing. Please rewrite along these lines: "...may contain. For function parameters, you can also use an inline @type tag to identify a parameter's type."
There was a problem hiding this comment.
This text works with my casting example, below, hence why it might be confusing. I've taken the suggestion though and made it about function parameters.
content/en/tags-type.md
Outdated
| @@ -297,3 +57,12 @@ var FOO = 1; | |||
| var FOO = 1; | |||
| ``` | |||
| {% endexample %} | |||
|
|
|||
| To indicate that a variable is of a certain type, you can cast it with @type. The surrounding | |||
There was a problem hiding this comment.
This appears to be a Closure Compiler thing that has nothing to do with JSDoc, so please remove this example.
There was a problem hiding this comment.
So: we have a bunch of examples that refer to Closure Compiler all around the site, and I strongly think that casting is a very important use of @type for Closure. With that in mind, I've updated the example to make it clear it's just for Closure—what do you think now?
To be clear, I'm very happy to be overruled, just stating my case a bit more clearly.
Resolves #154.
@hegemonic