--- @file docexample.lua 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/


--- 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.
function escapeEntities(str)

end

--- The table of escapes used by escapeEntities
--
-- The entries are processed in order
entities = {
   { "&", "apos" },
   { '"', "quot" },
   { '£', "pound" }
}

--- 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.
Class "ListNode" {
   --- Return the next ListNode in the List
   --
   -- @return node(ListNode,nil) Returns nil if this is the last ListNode
   function :GetNext()
      return self.next
   end
   --- Return the previous ListNode in the List
   --
   -- @return node(ListNode,nil) Returns nil if this is the first ListNode
   function :GetPrev()
      return self.prev
   end
   --- Return the value of this ListNode
   --
   -- @return value(*) The value of the ListNode could be of any type
   --                  including nil
   function :GetValue()
      return self.value
   end
}

--- Doubly linked list
--
-- A List object contains a doubly linked list of ListNode objects.
Class "List" {
   --- The List object will be empty when first created
   function :Constructor()
   end
   --- 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.
   function :Remove(node)
   end
}