#summary Documenting Functions

||Navigation>>||  [Manual Start]  ||  [AdvancedConfiguration Next- Advanced Configuration Options] || [ComplexTypes Previous - Complex Types] ||
-----


= Documenting Functions =

The simplest scenario of documenting a function was covered in [GettingStarted Getting Started] section.

This section would cover the following aspects:

  * Functions that has optional parameter(s)
  * Functions that accepts different sets of arguments
  * Functions that has "tuple" arguments (i.e. structure)
  * Functions that returns a "tuple" (structure)
  * Functions that has an array or an associative array (map) as a parameter 
  * Functions that accepts another function as parameter or returns a function
  * Other weird cases

*Note* While this section focuses mostly on documenting functions and uses [TagFunction @function] tags in the examples, all these rules would be applicable also to to documentation of [TagConstructor @constructor], [TagEvent @event] and [TagIfunction @ifunction] tags.

== Functions that has optional parameter(s) ==

This is the simplest case. The only thing that is needed, is to add the modifier *optional* to the parameter. For example, you have a function that performs a search in an array and can perform the search either from the beginning or from the end of the array. The indicator whether to search from the beginning or from the end is optional:
{{{
/**
@function search Performs search in an array
@param {Array} arr - array in which search should be performed
@param {Function} callback - function to be called for each element
@param {optional Boolean} backwards - whether the search should start from the beginning or from the end.
*/
function search(arr, callback, backwards)
{
....
}
}}}

In the generated documentation the optional parameters appear in square brackets:

{{{
function search(Array arr, Function callback, [Boolean backwards])

Parameters:
    arr - array in which search should be performed
    callback - function to be called for each element
    [backwards] - whether the search should start from the beginning or from the end.
}}}


== Functions that accepts different sets of arguments ==
While it is quite common in Java or C/C++ to have functions that have the same name but different signatures, it is not directly supported in JavaScript, although there are plenty tricks that could be used to achieve the same result. The big question is how to document that behavior properly.

The solution provided by jGrouseDoc is to use special tag [TagParamset @paramset]. For example, say, you would want to have an option to call the function from the previous example using Perl style, something like this:
{{{
   search({arr:myArray, callback:myCallback})
}}}
Also you definitely want to retain the classic syntax.
The jGrouseDoc comment to describe this behavior would be:
{{{
/**
@function ? Performs search in an array
@paramset Classic
@param {Array} arr - array in which search should be performed
@param {Function} callback - function to be called for each element
@param {optional Boolean} backwards - whether the search should start from the beginning 
@paramset Perl Way
@param {Object} obj - structure containing fields with arr, callback and backwards
*/
function search(arr, callback, backwards)
....
}}}

The generated documentation would look close to this:
{{{
  search(Array  arr, Function callback, [Boolean  backwards])
  search(Object obj)
Performs search in an array
Parameters:
Syntax 1 - Classic
   arr - array in which search should be performed
   callback - function to be called for each array element.
   [backwards] - whether the search should start from the beginning 
Syntax 2 - Perl Way
   obj - structure containing fields with arr, callback and backwards

}}}
 
== Functions that has "[http://en.wikipedia.org/wiki/Tuple tuple]" arguments (i.e. structure) ==

The example in the previous section has a drawback, namely from the description it is not clear what exactly would be the fields in the *obj* argument when the function is used in the Perl Way (one would guess anyway, but still...)

In order to address that concern, jGrouseDoc allows specification of the "tuple" structure using the [TagDotDotDot @...] tag. Conceptually the @... tag is quite close to @param tag  - it is possible to specify modifiers, type, member name and comment for the member. Using this tag, the comment could be rewritten the following way:

{{{
/**
@function ? Performs search in an array
@paramset Classic
@param {Array} arr - array in which search should be performed
@param {Function} callback - function to be called for each element
@param {optional Boolean} backwards - whether the search should start from the beginning 
@paramset Perl Way
@param {Object} obj - structure with arguments for the function
@... {Array} arr - array in which search should be performed
@... {Function} callback - function to be called for each element
@... {optional Boolean} backwards - whether the search should start from the beginning 
*/
function search(arr, callback, backwards)
....
}}}
 
The generated documentation would look close to this:
{{{
  search(Array  arr, Function callback, [Boolean  backwards])
  search(Object obj)
Performs search in an array
Parameters:
Syntax 1 - Classic
   arr - array to be iterated
   callback - function to be called for each array element.
   [backwards] - whether the search should start from the beginning 
Syntax 2 - Perl Way
   obj - structure with arguments for the function
       * Array arr - array in which search should be performed
       * Function callback - function to be called for each element
       * [Boolean backwards] - whether the search should start from the beginning  
}}}

Of course, if the structure that is used as an argument to the function could appear in other places, then it could be more practical to declare it separately using the [TagStruct @stuct] tag.

== Functions that returns a "tuple" (structure) ==
Consider an example, when you have a function that returns boundaries of an element. For some reason you don't want to declare special type for boundaries using [TagStruct @struct] or [TagClass @class] or similar tags, but you want simply specify that the returned structure has top, left, width and height fields.
The solution is quite simple and close to the one in the previous section, namely use the [TagDotDotDot @...] tag:
{{{
/**
@function {Object} getBoundaries - returns the boundaries for given element
@param {DOMElement} element - DOM element to be analyzed
@returns boundaries
@... {Number} top - top coordinate in pixels
@... {Number} left - left coordinate in pixels
@... {Number} width - width in pixels
@... {Number} height - height in pixels
*/
}}}

The produced documentation would look like this:
{{{
  function  getBoundaries
Object getBoundaries(DOMElement element)
- returns the boundaries for given element
Parameters:
    element - DOM element to be analyzed
Returns:
    boundaries
       * Number top - top coordinate in pixels
       * Number left - left coordinate in pixels
       * Number width - width in pixels
       * Number height - height in pixels
}}}

== Functions that has an array or an associative array (map) as a parameter ==
Briefly, if you need to declare that your function accepts an array of Strings as a parameter, then you can specify String`[]` as the type of this parameter. If the function returns a typed array, say of type MyClass, then you can specify MyClass`[]` as return type, like this:

{{{
/**
@function {MyClass[]} getSomeData 
@returns array with MyClass structures
*/
}}}
See the section [ComplexTypes Arrays and Associative Arrays] for additional details 

== Functions that accepts another function as parameter or returns a function ==

In the examples with *search* function it is not quite clear what kind of functions could be passed as a callback parameter.

There are two ways to provide this information in the documentation regarding the signature of the callback.
The first case is when the signature of the callback is trivial and self-explanatory. In this case the function description could be provided in the following form:
{{{
/**
@function search Performs search in an array
@param {MyClass[]} arr - array in which search should be performed
@param {function(MyClass element, int index)} callback - function to be called for each element
@param {optional Boolean} backwards - whether the search should start from the beginning or from the end.
*/
}}}

The produced result would be the following:
{{{
  function  search
search(MyClass[] arr, function(MyClass element, int index) callback, [Boolean backwards])
Performs search in an array
Parameters:
   arr - array in which search should be performed
   callback - function to be called for each element
   [backwards] - whether the search should start from the beginning or from the end.
}}}

While this approach is quite simple, it has certain drawbacks. First, the system won't parse the string "function(MyClass element, int index)" and won't analyze parameter types and other information in order to provide hyperlinks, etc. There is no convenient way to describe the meaning of parameters and return type.

The alternative is to declare the function interface separately using [TagIfunction @ifunction] tag. The example above could be re-written in the following way:

{{{
/**
@ifunction {Boolean} SearchCallback
@param {MyClass} item - item to be analyzed
@param {Number} index - index of item in array
@returns true if the item matches the required condition
*/

/**
@function search Performs search in an array
@param {MyClass[]} arr - array in which search should be performed
@param {SearchCallback} callback - function to be called for each element
@param {optional Boolean} backwards - whether the search should start from the beginning or from the end.
*/
}}}

The produced result would be like this:

{{{

  ifunction  SearchCallback
Boolean SearchCallback(MyClass item, Number index)
Parameters:
   item - item to be analyzed
   index - index of item in array
Returns:
   true if the item matches the required condition 


 search(MyClass[]  arr, SearchCallback  callback, [Boolean  backwards])
Performs search in an array
Parameters:
   arr - array in which search should be performed
   callback - function to be called for each element
   [backwards] - whether the search should start from the beginning or from the end.
}}}

Note that in this case the reference to SearchCallback in definition of *search* would appear as a hyperlink to actual definition of the callback interface.

The examples above show how to deal cases when a function is being passed as a parameter. Exactly the same approach could be taken when you have a function that returns another function:

{{{
/**
@function {function(refObject)} createCallback
*/
}}}

or 

{{{
/**
@ifunction (Boolean} SuperCallback
@param {MyClass} refObject
*/

/**
@function {SuperCallback} createCallback
*/
}}}


== Other weird cases ==
Consider a function that sets boundaries for an object. The developer wants to provide ability to specify the boundaries in {x, y, w, h} or {left, top, width, height} or something like {x, y, width, height}. Essentially, left is an alias for x, width is an alias for w, etc. The goal is to provide documentation for such behavior so it would be clear that _either_ x _or_ left could be specified and so forth.
The following example shows how it could be achieved:
{{{
/**
@function setRect
@param boundaries
@... "left or x" - horizontal coordinate
@... "top or y" - vertical coordinate
@... "width or w" - width
@... "height or h" - height
*/
}}}

The produced documentation would appear like this:

{{{
  function  setRect
setRect( boundaries)
Parameters:
   boundaries
      * left or x - horizontal coordinate
      * top or y - vertical coordinate
      * width or w - width
      * height or h - height
}}}

The quoted names are allowed only when using [TagParam @param] and [TagDotDotDot @...] tags

-----
||Navigation>>||  [Manual Start]  ||  [AdvancedConfiguration Next- Advanced Configuration Options] || [ComplexTypes Previous - Complex Types] ||