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 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: