Type Definitions

Vasyl Zuzyak edited this page Jun 21, 2014 · 5 revisions

Type definitions (specified like {Number/String}) must follow a rigid specification.

JSDuck supports a basic syntax which is used throughout ExtJS documentation and the syntax supported by Google Closure Compiler.

The basic syntax

This list covers what you can do with the basic syntax:

  • {"blah"} - a string value "blah".
  • {42} - a number value 42.
  • {Ext.Element} - a single Ext.Element.
  • {Ext.Element/Object} - a single Ext.Element or plain object
  • {String[]} - array of strings.
  • {String[][]} - 2D array of strings.
  • {Boolean/"top"/"bottom"} - either boolean, or String "top" or "bottom".
  • {String...} - variable number of string arguments.

These of course can be combined. For example:

  • {String[]/Number[]...} - variable number of string or number arrays.

Multiple types can be separated by either a slash (/) or a pipe (|). Whichever you choose, be consistent within your project.

Google Closure Compiler Type Expressions

For more expressive power Google Closure Compiler Type Expressions allow you to write complex type expressions like this:

  • {function((number|string), RegExp=): boolean} - a function taking two arguments (first a number or string, second a RegExp which is optional) and returning a boolean.

Type names

JSDuck will also check that you don't reference any unknown types. For example if you specify {Foo} and you don't have class Foo included to you documentation, JSDuck will produce a warning. Warnings aren't thrown for JavaScript primitive types:

  • boolean
  • number
  • string
  • undefined
  • void

for built-in JavaScript types:

  • Object
  • String
  • Number
  • Boolean
  • RegExp
  • Function
  • Array
  • Arguments
  • Date
  • Error
  • null

and for few DOM types:

  • HTMLElement
  • XMLElement
  • NodeList
  • TextNode
  • CSSStyleSheet
  • CSSStyleRule
  • Event

To make JSDuck ignore some other type names use --external=Foo,Bar,...

To document a variable that can be of any type whatsoever, use the Mixed type. But try to keep its use to the minimum, always prefer the {Foo/Bar/Baz} or {Foo|Bar|Baz} syntax to list possible types.