From ce84a003a426743f7379223da42f868cf5d79efe Mon Sep 17 00:00:00 2001
From: gyani <gyani@e0a8ed71-7df4-0310-8962-fdc924857419>
Date: Sun, 14 Jun 2015 06:20:06 +0000
Subject: [PATCH] Added documentation for parseDOM. Fixed a few typos in the
 original documentation

---
 nselib/slaxml.lua | 62 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 57 insertions(+), 5 deletions(-)

diff --git a/nselib/slaxml.lua b/nselib/slaxml.lua
index 4e134ebf4..d3be644fc 100644
--- a/nselib/slaxml.lua
+++ b/nselib/slaxml.lua
@@ -9,6 +9,7 @@
 -- The streaming parser does a simple pass through the input and reports what it sees along the way.
 -- You can optionally ignore white-space only text nodes using the <code>stripWhitespace</code> option.
 -- The library contains the parser class and the parseDOM function.
+--
 -- Basic Usage of the library:
 -- <code>
 -- local parser = parser:new()
@@ -32,7 +33,57 @@
 -- <code>
 -- parseDOM(xmlbody, options)
 -- </code>
--- @author "Gavin Kistner<original pure lua implemetation>, Gyanendra Mishra<nse specific implementation>"
+--
+-- DOM Table Features
+--
+-- Document - the root table returned from the parseDOM() method.
+-- <code>doc.type</code> : the string "document"
+-- <code>doc.name</code> : the string "#doc"
+-- <code>doc.kids</code> : an array table of child processing instructions, the root element, and comment nodes.
+-- <code>doc.root</code> : the root element for the document
+--
+-- Element
+--
+-- <code>someEl.type</code> : the string "element"
+-- <code>someEl.name</code> : the string name of the element (without any namespace prefix)
+-- <code>someEl.nsURI</code> : the namespace URI for this element; nil if no namespace is applied
+-- <code>someEl.attr</code> : a table of attributes, indexed by name and index
+-- <code>local value = someEl.attr['attribute-name']</code> : any namespace prefix of the attribute is not part of the name
+-- <code>local someAttr = someEl.attr[1]</code> : an single attribute table (see below); useful for iterating all 
+-- attributes of an element, or for disambiguating attributes with the same name in different namespaces
+-- <code>someEl.kids</code> : an array table of child elements, text nodes, comment nodes, and processing instructions
+-- <code>someEl.el</code> : an array table of child elements only
+-- <code>someEl.parent</code> : reference to the parent element or document table
+--
+-- Attribute
+--
+-- <code>someAttr.type</code> : the string "attribute"
+-- <code>someAttr.name</code> : the name of the attribute (without any namespace prefix)
+-- <code>someAttr.value</code> : the string value of the attribute (with XML and numeric entities unescaped)
+-- <code>someAttr.nsURI</code> : the namespace URI for the attribute; nil if no namespace is applied
+-- <code>someAttr.parent</code> : reference to the owning element table
+--
+-- Text - for both CDATA and normal text nodes
+-- <code>someText.type</code> : the string "text"
+-- <code>someText.name</code> : the string "#text"
+-- <code>someText.value</code> : the string content of the text node (with XML and numeric entities unescaped for non-CDATA elements)
+-- <code>someText.parent</code> : reference to the parent element table
+--
+-- Comment
+--
+-- <code>someComment.type</code> : the string "comment"
+-- <code>someComment.name</code> : the string "#comment"
+-- <code>someComment.value</code> : the string content of the attribute
+-- <code>someComment.parent</code> : reference to the parent element or document table
+--
+-- Processing Instruction
+--
+-- <code>someComment.type</code> : the string "pi"
+-- <code>someComment.name</code> : the string name of the PI, e.g. <?foo …?> has a name of "foo"
+-- <code>someComment.value</code> : the string content of the PI, i.e. everything but the name
+-- <code>someComment.parent</code> : reference to the parent element or document table
+--
+-- @author {"Gavin Kistner<original pure lua implemetation>", "Gyanendra Mishra<NSE specific implementation>"}
 
 --[=====================================================================[
 v0.7 Copyright © 2013-2014 Gavin Kistner <!@phrogz.net>; MIT Licensed
@@ -56,7 +107,7 @@ local debugging_level = tonumber(stdnse.get_script_args('slaxml.debug')) or 3
 local DEFAULT_CALLBACKS = {
     --- A call back for processing instructions.
     -- To use define pi = function(<target>, <content>) <function body> end in parser._call table.
-    -- Executes whenever a comment is found.
+    -- Executes whenever a processing instruction is found.
     -- @param target the PI target
     -- @param content any value not containing the sequence  '?>'
     pi = function(target,content)
@@ -126,6 +177,7 @@ parser = {
     return o
   end,
   --- Parses the xml in sax like manner.
+  -- @self The parser object.
   -- @param xml The xml body to be parsed.
   -- @param options Options if any specified.
   parseSAX = function(self, xml, options)
@@ -333,9 +385,9 @@ parser = {
 
 }
 
---- Parses xml and spits out dom
--- @param xml, the xml body to be parsed.
--- @param options if any to use. Supporst stripWhitespaces currently.
+--- Parses xml and outputs a  dom table.
+-- @param xml the xml body to be parsed.
+-- @param options if any to use. Supports <code>stripWhitespaces</code> currently.
 function parseDOM (xml, options)
   if not options then options={} end
   local rich = not options.simple