#summary A "how to" guide for documenting various constructs

== Arrays of a Known Type ==
If you have a property that is an array of a known type, just give it's type as _typename_ followed by "[]".  For example:
{{{
/**
 * This is an array of numbers
 *
 * @var {Number[]} myVar
 */
}}}

== Documenting Function Signatures ==
The `@function` tag is great for when you need to document a normal function, but there are a number of patterns where `@function` isn't appropriate.

=== Event Handlers  ===
Let's say you have an object that supports a "onSomeEvent" property - a property that can be set to a function that will be called when "some event" happens.  In this case, use `@event` to document the expected signature. For example:

{{{
/**
 * Called when "some event" happens
 *
 * @event {Boolean} onSomeEvent
 * @param {Object} object The object that triggered the event
 * @param {Object} arg1 A second argument to the event
 * @return Return false to cancel the event, or true to let it continue
 */
}}}

=== Functions as Arguments ===
Things can get a bit tricky if you need to document the expected signature of a function passed as an argument to another function.   In this case, use `@ifunction` to create a named method signature that you can refer to like any other data type.  For example:

{{{
/**
 * Call a function at a certain time.
 *
 * @function callAtTime
 * @param {TimerFunction} func The function to call (note the reference to
 * 'TimerFunction', which we define below')
 * @param {Date} time The time to call the function
 */

/**
 * Here's where we document the expected signature for 'func', above.  We
 * document that it will be passed the date it was due to be called, and that
 * it can return a Date.
 *
 * @ifunction {Date} TimerFunction
 * @param {Date} date The date passed to callAtTime
 * @return You may optionally return a Date to request that the function be
 * invoked again.  It is an error to return a Date that it not more recent than
 * `date`.
 */
}}}

=== Functions as Return Values ===
If a method returns a function, the signature of that returned function can be documented in a fashion similar to Functions as Arguments (above).  For example:

{{{
/**
 * Create a Date formatter function
 *
 * @function {DateFormatterFunction} getDateFormatter
 * @param {String} format A format string of some sort
 */

/**
 * Define the signature of the function returned by getDateFormatter
 *
 * @ifunction {String} DateFormatterFunction
 * @param {Date} date The date object to convert to a string
 */
}}}