#summary Documenting complex types

||Navigation>>||  [Manual Start]  ||  [AdvancedFunction  Next - Documenting Functions ] || [ModifierReference Previous - Modifiers] ||

-----------

== Documenting Arrays and Associative Arrays (Maps) Types ==

One of the common problems with JavaScript libraries is that there are no ways to specify the type of elements that are contained in arrays or in maps. In certain cases it is sufficient to assume that the code is working with generic array, but there are plenty of cases when the code anticipates that all elements of array are of certain type. jGrouseDoc provides additional support for documentation of those cases.
In a nutshell, it is quite simple. If you need to document that your code anticipates array of Strings, simply specify *`String[]`* as a type. If the elements are of type *`MyCustomClass`* (declared somewhere else in your documentation) then specify *`MyCustomClass[]`* and jGrouseDoc would conveniently put a hyperlink when rendering the reference to *`MyCustomClass`*.

Similar approach is taken for documenting of [http://en.wikipedia.org/wiki/Associative_array associative arrays] (maps). Normally in JavaScript maps are based on adding properties to an instance of Object. That approach has an implicit assumption that all keys are strings, but it does not provide any idea what are the values. jGrouseDoc's solution to this problem is simple - say, you need to declare the fact that specific parameter is a map that uses String as keys and *`MyCustomClass`* as values. This type could be declared in jGrouseDoc as *`MyCustomClass[String]`*. If you have a map with keys having type *`MyCustomKey`* and values of *`MyCustomClass`* then such map could be described as *`MyCustomClass[MyCustomKey]`*. When rendering such definition in the produced documentation, jGrouseDoc would conveniently replace the references to *`MyCustomClass`* and *`MyCustomKey`* with hyperlinks to definition of those clases/types.

To illustrate, consider that you have a function that accepts a map as a parameter and returns an array with values from that map. Such function could be documented in this fashion:

{{{
/**
@function {MyValueClass[]} getValues
@param {MyValueClass[MyKeyClass]} map - associative array with keys of type {@link MyKeyClass} and values of type {@link MyValueClass}
@returns sorted array with values
*/
}}}

This would produce the following output:

||http://jgrousedoc.googlecode.com/svn/trunk/docs/complexParams.gif||

------------
||Navigation>>||  [Manual Start]  ||  [AdvancedFunction  Next - Documenting Functions ] || [ModifierReference Previous - Modifiers] ||