NSE Script Documentation

["Patrick Donnelly" <batrick.donnelly () gmail com>]

Hey folks,

I've been working on the Documentation system this week for NSE. The
format of the documents will be very similar to LuaDoc (see:
http://seclists.org/nmap-dev/2008/q2/0273.html). The main difference
is NSEDoc requires the script writer to declare what is being
documented, e.g. variables, functions, etc. The other difference is
NSEDoc maintains and returns the data it collects from the scripts for
use by NSE. An example script using the documentation system is
attached.

The commented documentation follows this format:

--- [identifier] type scope
-- General description.
-- @tag description
-- @tag description
-- above tag's description continued...

Identifier should be the name of the function or variable being
documented. Type is one of the following:
 -- file
Documents the file itself. The "General description" would be what
normally is put in the description field for a script
(http://nmap.org/book/nse-scripts.html#nse-format-description). The
tags would document other aspects such as the author or copyright.
 -- hostrule
Documents the hostrule. Of course the hostrule is a function (another
type below), it is separated to distinguish it. The hostrule will be
shown separately from other functions in the generated Docs.
 -- portrule
Same as hostrule above.
 -- action
Same as hostrule above.
 -- function
Documents a function.
 -- class
Documents a class.
 -- variable
Documents a variable (local or global)

Scope is either global or local.

For some types (such as hostrule), the identifier is optional (as it's implied).

Some tags below:
 -- author
 -- category
 -- class
 -- copyright
 -- output
 -- param
 -- namespace
 -- return
 -- require
 -- see
 -- usage

Hopefully the tags are self explanatory. All tags are valid for all
types, some tags will however be ignored when output (documentation)
is generated.

I'm hoping to have an example of the actual documentation with more
information (html) later this week.

Cheers,

-- 
-Patrick Donnelly

"One of the lessons of history is that nothing is often a good thing
to do and always a clever thing to say."

-Will Durant

Attachment: anonFTP.nse
Description:

_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://SecLists.Org