/*-- @file docexample.c Documentation examples
 *
 * The purpose of this file is to show some examples of documentation
 * styles so that we can play with how to document Aranha modules etc.
 *
 * @author Daniel Silverstone <dsilvers@digital-scurf.org>
 * @homepage http://aranha.pepperfish.net/docs/
 */

/*-- @function escapeEntities Escape a string using HTML entities
 *
 * Much of HTML needs escaping, especially when passing form values around
 * across reloads. This function does that for you
 *
 * @param str(string) The string to escape
 * @return estr(string) The string having had HTML escapes applied to it.
 */

/*-- @variable entities The table of escapes used by escapeEntities
 *
 * The entries are processed in order
 */

/*-- @class ListNode The component part of the List class
 *
 * A ListNode contains references to the next and previous nodes
 * in the List. It also contains a value for that node.
 */

/*-- @method ListNode:GetNext Return the next ListNode in the List
 *
 * @return node(ListNode,nil) Returns nil if this is the last ListNode
 */


/*-- @method ListNode:GetPrev Return the previous ListNode in the List
 *
 * @return node(ListNode,nil) Returns nil if this is the first ListNode
 */

/*-- @method ListNode:GetValue Return the value of this ListNode
 *
 * @return value(*) The value of the ListNode could be of any type
 *                  including nil
 */


/*-- @class List Doubly linked list
 *
 * A List object contains a doubly linked list of ListNode objects.
 */


/*-- @constructor ListNode The List object will be empty when first created
 */

/*-- @method ListNode:Remove Remove the specified node from the list
 *
 * Note that strange and wonderful (read dangerous and undefined) things
 * may happen if you try to remove a ListNode from a List which does not
 * own it.
 *
 * Note that this function will also (quite deliberately) trash the supplied
 * ListNode object so if you need its value, call ListNode:GetValue() on it
 * before you remove it from the list.
 *
 * @param node(ListNode) The node to remove.
 */