Updated all libraries documentation.

packet and url both need more work.

nselib/base64.lua

@@ -1,8 +1,7 @@
---- Base64 library
+--- Base64 library. Follows RFC4648.
+--@author Philip Pickering <pgpickering@gmail.com>
 --@copyright See nmaps COPYING for licence
 
--- as in RFC4648
--- author: Philip Pickering <pgpickering@gmail.com>
 -- thanks to Patrick Donnelly for some optimizations
 
 module(... or "base64",package.seeall)

nselib/bit.luadoc

@@ -0,0 +1,43 @@
+--- BitLib is a library by Reuben Thomas that provides facilities for
+-- bitwise operations on Integer values.
+-- @author Reuben Thomas
+-- @copyright BSD License
+
+--- Cast a to an internally-used integer type.
+-- @param a Number.
+function bit.cast(a)
+
+--- Return the one's complement of a.
+-- @param a Number.
+-- @return The one's complement of a.
+function bit.bnot(a)
+
+--- Returns the bitwise and of all its arguments.
+-- @param ... A variable number of Numbers to and.
+-- @return The anded result.
+function bit.band(...)
+
+--- Returns the bitwise or of all its arguments.
+-- @param ... A variable number of Numbers to or.
+-- @return The ored result.
+function bit.bor(...)
+
+--- Returns the bitwise exclusive or of all its arguments.
+-- @param ... A variable number of Numbers to exclusive or.
+-- @return The exclusive ored result.
+function bit.bxor(...)
+
+--- Returns a left shifted by b places.
+-- @param a Number to perform the shift on.
+-- @param b Number of shifts.
+function bit.lshift(a, b)
+
+--- Returns a right shifted by b places.
+-- @param a Number to perform the shift on.
+-- @param b Number of shifts.
+function bit.rshift(a, b)
+
+--- Returns a arithmetically shifted by b places.
+-- @param a Number to perform the shift on.
+-- @param b Number of shifts.
+function bit.arshift(a, b)

nselib/comm.lua

@@ -1,8 +1,21 @@
--- Kris Katterjohn 04/2008
+--- The comm module provides functions for common network discovery tasks.
+-- Banner-grabbing and making a quick exchange of data are some of
+-- these tasks. These
+-- functions' return values are setup for use with exception handling
+-- via nmap.new_try().\n
+-- \n
+-- These functions can all be passed a table of options, but it's not
+-- required. The relevant indexes for this table are bytes, lines, proto
+-- and timeout. bytes is used to provide the minimum number of bytes required
+-- for a read. lines does the same, but for the minimum number of lines.
+-- proto is used to set the protocol to communicate with, defaulting to
+-- "tcp" if not provided. timeout is used to set the socket timeout (see
+-- the socket function set_timeout() for details). 
+-- @author Kris Katterjohn 04/2008
 
 module(... or "comm", package.seeall)
 
-------
+--
 --
 -- The Functions:
 --
@@ -91,6 +104,15 @@ local read = function(sock, opts)
 	return status, response
 end
 
+--- This function simply connects to the specified port number on the
+-- specified host and returns any data received. bool is a Boolean value
+-- indicating success. If bool is true, then the second returned value
+-- is the response from the target host. If bool is false, an error
+-- message is returned as the second value instead of a response. 
+-- @param host The host to connect to.
+-- @param port The port on the host.
+-- @param opts The options. See module description.
+-- @return bool, data
 get_banner = function(host, port, opts)
 	opts = initopts(opts)
 
@@ -109,6 +131,17 @@ get_banner = function(host, port, opts)
 	return status, ret
 end
 
+--- This function connects to the specified port number on the specified
+-- host, sends data, then waits for and returns the response, if any.
+-- bool is a Boolean value indicating success. If bool is true, then the
+-- second returned value is the response from the target host. If bool is
+-- false, an error message is returned as the second value instead of a
+-- response. 
+-- @param host The host to connect to.
+-- @param port The port on the host.
+-- @param data The data to send initially.
+-- @param opts The options. See module description.
+-- @return bool, data
 exchange = function(host, port, data, opts)
 	opts = initopts(opts)
 

nselib/datafiles.lua

@@ -1,4 +1,7 @@
--- Kris Katterjohn 03/2008
+--- The datafiles module provides functions for reading and parsing Nmap's
+-- data files. For example nmap-protocol, nmap-rpc, etc. These functions'
+-- return values are setup for use with exception handling via nmap.new_try().
+-- @author Kris Katterjohn 03/2008
 
 module(... or "datafiles", package.seeall)
 
@@ -95,6 +98,12 @@ local fillservices = function()
 	return true
 end
 
+--- This function reads and parses Nmap's nmap-protocols file.
+-- bool is a Boolean value indicating success. If bool is true, then the
+-- second returned value is a table with protocol numbers indexing the
+-- protocol names. If bool is false, an error message is returned as the
+-- second value instead of the table. 
+-- @return bool, table|err
 parse_protocols = function()
 	if not filltable("nmap-protocols", protocols_table) then
 		return false, "Error parsing nmap-protocols"
@@ -103,6 +112,12 @@ parse_protocols = function()
 	return true, protocols_table
 end
 
+--- This function reads and parses Nmap's nmap-rpc  file. bool is a
+-- Boolean value indicating success. If bool is true, then the second
+-- returned value is a table with RPC numbers indexing the RPC names.
+-- If bool is false, an error message is returned as the second value
+-- instead of the table. 
+-- @return bool, table|err
 parse_rpc = function()
 	if not filltable("nmap-rpc", rpc_table) then
 		return false, "Error parsing nmap-rpc"
@@ -111,6 +126,16 @@ parse_rpc = function()
 	return true, rpc_table
 end
 
+--- This function reads and parses Nmap's nmap-services file.
+-- bool is a Boolean value indicating success. If bool is true,
+-- then the second returned value is a table containing two other
+-- tables: tcp{} and udp{}. tcp{} contains services indexed by TCP port
+-- numbers. udp{} is the same, but for UDP. You can pass "tcp" or "udp"
+-- as an argument to parse_services() to only get the corresponding table.
+-- If bool is false, an error message is returned as the second value instead
+-- of the table. 
+-- @param protocol The protocol table to return.
+-- @return bool, table|err
 parse_services = function(protocol)
 	if protocol and protocol ~= "tcp" and protocol ~= "udp" then
 		return false, "Bad protocol for nmap-services: use tcp or udp"

nselib/http.lua

@@ -1,4 +1,17 @@
--- See nmaps COPYING for licence
+--- The http module provides functions for dealing with the client side
+-- of the http protocol. The functions reside inside the http namespace.
+-- The return value of each function in this module is a table with the
+-- following keys: status, header and body. status is a number representing
+-- the HTTP status code returned in response to the HTTP request. In case
+-- of an unhandled error, status is nil. The header value is a table
+-- containing key-value pairs of HTTP headers received in response to the
+-- request. The header names are in lower-case and are the keys to their
+-- corresponding header values (e.g. header.location = "http://nmap.org/").
+-- Multiple headers of the same name are concatenated and separated by
+-- commas. The body value is a string containing the body of the HTTP
+-- response.
+-- @copyright See nmaps COPYING for licence
+
 module(... or "http",package.seeall)
 
 require 'stdnse'
@@ -19,7 +32,19 @@ require 'url'
 -- in case of an error status is nil
 
 
--- fetch relative URL with get request
+--- Fetches a resource with a GET request. The first argument is either a
+-- string with the hostname or a table like the host table passed by nmap.
+-- The second argument is either the port number or a table like the port
+-- table passed by nmap. The third argument is the path of the resource.
+-- The fourth argument is a table for further options. The table may have
+-- 2 keys: timeout and header. timeout is the timeout used for the socket
+-- operations. header is a table with additional headers to be used for
+-- the request. The function builds the request and calls http.request.
+-- @param host The host to query.
+-- @param port The port for the host.
+-- @param path The path of the resource.
+-- @param options A table of optoins. See function description.
+-- @return table
 get = function( host, port, path, options )
   options = options or {}
   local presets = {Host=host,Connection="close",['User-Agent']="Mozilla/5.0 (compatible; Nmap Scripting Engine; http://nmap.org/book/nse.html)"}
@@ -41,9 +66,15 @@ get = function( host, port, path, options )
   return request( host, port, data, options )
 end
 
--- fetch URL with get request
-get_url = function( u, options )
-  local parsed = url.parse( u )
+--- Parses url and calls http.get with the result. The second argument
+-- is a table for further options. The table may have 2 keys: timeout
+-- and header. timeout is the timeout used for the socket operations.
+-- header is a table with additional headers to be used for the request. 
+-- @param url The url of the host.
+-- @param options Options passed to http.get.
+-- @see http.get
+get_url = function(url, options )
+  local parsed = url.parse( url )
   local port = {}
 
   port.service = parsed.scheme
@@ -65,9 +96,19 @@ get_url = function( u, options )
   return get( parsed.host, port, path, options )
 end
 
--- send http request and return the result as table
--- host may be a table or the hostname
--- port may be a table or the portnumber
+--- Sends request to host:port and parses the answer. The first argument
+-- is either a string with the hostname or a table like the host table
+-- passed by nmap. The second argument is either the port number or a
+-- table like the port table passed by nmap. SSL is used for the request
+-- if either port.service  equals https or port.version.service_tunnel
+-- equals ssl. The third argument is the request. The fourth argument is
+-- a table for further options. You can specify a timeout for the socket
+-- operations with the timeout key. 
+-- @param host The host to query.
+-- @param port The port on the host.
+-- @param data Data to send initially to the host.
+-- @param options Table of options.
+-- @see http.get
 request = function( host, port, data, options )
   options = options or {}
 

nselib/ipOps.lua

@@ -1,8 +1,14 @@
--- See nmaps COPYING for licence
+--- General IP Operations.
+-- @copyright See nmaps COPYING for licence
+
 module(... or "ipOps",package.seeall)
 
-
--- check to see if ip is part of RFC 1918 address space
+--- Checks whether an IP address, provided as a string in dotted-quad
+-- notation, is part of the non-routed private IP address space,
+-- as described in RFC 1918. These addresses are the well-known
+-- 10.0.0.0/8, 192.168.0.0/16 and 172.16.0.0/12 networks. 
+-- @param ip Dotted-Quad IP address.
+-- @return boolean Is private IP
 isPrivate = function(ip)
 	local a, b
 	a, b = get_parts_as_number(ip)  
@@ -16,12 +22,20 @@ isPrivate = function(ip)
 	return false
 end
 
+--- Returns the IP address as DWORD value (i.e. the IP <a.b.c.d> becomes
+-- (((a*256+b)*256+c)*256+d) ) 
+-- @param ip Dotted-Quad IP address.
+-- @return IP Address as a DWORD value.
 todword = function(ip)
 	local a, b, c, d
 	a,b,c,d = get_parts_as_number(ip) 
 	return (((a*256+b))*256+c)*256+d
 end
 
+--- Returns 4 numbers corresponding to the fields in dotted-quad notation.
+-- For example, ipOps.get_parts_as_number("192.168.1.1")  returns 192,168,1,1. 
+-- @param ip Dotted-Quad IP address.
+-- @return Four numbers in the IP address.
 get_parts_as_number = function(ip)
 	local a,b,c,d = string.match(ip, "(%d+)%.(%d+)%.(%d+)%.(%d+)")
 	a = tonumber(a);

nselib/listop.lua

@@ -1,4 +1,12 @@
--- See nmaps COPYING for licence
+--- Functional Programming Style List Operations.\n\n
+-- People used to programming in functional languages, such as Lisp
+-- or Haskell, appreciate their handling of lists very much. The listop
+-- module tries to bring much of the functionality from functional languages
+-- to Lua using Lua's central data structure, the table, as a base for its
+-- list operations. Highlights include a map function applying a given
+-- function to each element of a list. 
+--@copyright See nmaps COPYING for licence
+
 module(... or "listop", package.seeall)
 
 --[[
@@ -25,18 +33,25 @@ Functional programming style 'list' operations
     where 'value' is an lua datatype
 --]]
 
--- true if l is empty
+--- Determines if the list is empty.
+-- @param l A list.
+-- @return boolean
 function is_empty(l)
   return #l == 0 and true or false;
 end
 
--- true if l is a list
+--- Determines if l is a list (rather, a table).
+-- @param l A list.
+-- @return boolean
 function is_list(l)
   return type(l) == 'table' and true or false;
 end
 
--- Pass each elements of l to a function f which takes a single
--- argument. All the results are returned in an list
+--- Calls f for each element in the list. The returned list contains
+-- the results of each function call.
+-- @param f The function to call.
+-- @param l A list.
+-- @return List
 function map(f, l) 
     local results = {}
     for _, v in ipairs(l) do
@@ -45,16 +60,23 @@ function map(f, l)
     return results;
 end
 
--- Pass all elements of l to function f which takes a variable 
--- number of arguments or a number of arguments equal to the
--- size of l. The result of f is returned
+--- Calls the function with all the elements in the list as the parameters.
+-- @param f The function to call.
+-- @param l A list.
+-- @return Results from f.
 function apply(f, l)
   return f(unpack(l))
 end
 
--- Pass all elements of l to a predicate function f which takes a single
--- argument. All elements where f(l[x]) is true are returned in an 
--- indexed list
+--- Returns a list containing only those elements for which the predicate
+-- returns true. The predicate has to be a function, which takes an element
+-- of the list as argument and the result of which is interpreted as a
+-- Boolean value. If it returns true (or rather anything besides false
+-- and nil) the argument is appended to the return value of filter. For
+-- example: listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) returns {1,2,3,4}. 
+-- @param f The function.
+-- @param l The list.
+-- @return List
 function filter(f, l) 
   local results = {}
   for i, v in ipairs(l) do
@@ -65,32 +87,48 @@ function filter(f, l)
   return results
 end
 
--- return first element of a list
+--- Fetch the first element of a list.
+-- @param l The List.
+-- @return The first element.
 function car(l)
   return l[1]
 end
 
--- return everything but the first element of a list
+--- Fetch all elements following the first in a new List.
+-- @param l The List.
+-- @return List
 function cdr(l)
   return {unpack(l, 2)}
 end
 
--- same as car but start at element x
+--- Fetch element x from l.
+-- @param l The List.
+-- @param x Element index.
+-- @return Element x or 1.
 function ncar(l, x)
   return l[x or 1];
 end
 
--- same as cdr but start at element x
+--- Fetch all elements following the x or the first in a new List.
+-- @param l The List.
+-- @param x Element index.
+-- @return List
 function ncdr(l, x) 
   return {unpack(l, x or 2)};
 end
 
--- prepend a value or list to another value or list
+--- Prepend a value or list to another value or list.
+-- @param v1 value or list
+-- @param v2 value or list
+-- @return List
 function cons(v1, v2)
     return{ is_list(v1) and {unpack(v1)} or v1, is_list(v2) and {unpack(v2)} or v2}
 end
 
--- concatenate two lists and return the result
+--- Concatenate two lists and return the result.
+-- @param l1 List
+-- @param l2 List
+-- @return List
 function append(l1, l2)
     local results = {unpack(l1)}
 
@@ -100,7 +138,9 @@ function append(l1, l2)
     return results
 end
 
--- returned l in reverse order
+--- Return l in reverse order.
+-- @param l List.
+-- @return List
 function reverse(l)
     local results = {}
     for i=#l, 1, -1 do
@@ -109,7 +149,10 @@ function reverse(l)
     return results
 end
 
--- return a flat version of nested list l
+--- Return a flattened version of the List, l. All lists within l are
+-- replaced by its contents.
+-- @param l The list to flatten.
+-- @return List
 function flatten(l)
     local function flat(r, t)
     	for i, v in ipairs(t) do

nselib/match.lua

@@ -1,4 +1,7 @@
--- See nmaps COPYING for licence
+--- Provides functions which can be used for delimiting data received
+-- by receive_buf() function in the Network I/O API.
+--@copyright See nmaps COPYING for licence
+
 module(... or "match",  package.seeall)
 require "pcre"
 
@@ -10,6 +13,14 @@ require "pcre"
 -- sock:receivebuf(numbytes(80)) - is the buffered version of 
 --                                 sock:receive_bytes(80) - i.e. it returns
 --                                 exactly 80 bytes and no more 
+
+--- This is actually a wrapper around NSE's PCRE library exec function,
+-- thus giving script developers the possibility to use regular expressions
+-- for delimiting instead of Lua's string patterns. If you want to get the
+-- data in chunks separated by pattern (which has to be a valid regular
+-- expression), you would write:
+-- status, val = sockobj:receive_buf(match.regex("pattern")). 
+-- @param The regex.
 regex = function(pattern)
 	local r = pcre.new(pattern, 0,"C")
 
@@ -19,6 +30,12 @@ regex = function(pattern)
 	end
 end
 
+--- Takes a number as its argument and returns that many bytes. It can be
+-- used to get a buffered version of sockobj:receive_bytes(n) in case a
+-- script requires more than one fixed-size chunk, as the unbuffered
+-- version may return more bytes than requested and thus would require
+-- you to do the parsing on your own. 
+-- @param num Number of bytes.
 numbytes = function(num)
 	local n = num
 	return function(buf)

nselib/packet.lua

@@ -1,14 +1,9 @@
--- license = "See nmaps COPYING for license"
+--- Facilities for manipulating raw packets.
+-- @copyright See nmaps COPYING for license
+-- @author Marek Majkowski <majek04+nse@gmail.com>
+
 module(... or "packet" ,package.seeall)
 
--- Raw package parsing functions. Used with raw sockets
--- in nse.
--- Author: Marek Majkowski <majek04+nse@gmail.com>
-
---[[
---]]
-
-
 require "bit"
 
 

nselib/shortport.lua

@@ -1,6 +1,18 @@
--- See nmaps COPYING for licence
+--- Functions for common port tests.\n\n
+-- Takes a number as its argument and returns that many bytes.
+-- It can be used to get a buffered version of sockobj:receive_bytes(n) in
+-- case a script requires more than one fixed-size chunk, as the unbuffered
+-- version may return more bytes than requested and thus would require you
+-- to do the parsing on your own. 
+--@copyright See nmaps COPYING for licence
+
 module(... or "shortport", package.seeall)
 
+--- The port argument is either a number or a table of numbers which are
+-- interpreted as port numbers, against which the script should run. See
+-- module description for other arguments.
+-- @param port The port or list of ports to run against
+-- @return Function for the portrule.
 portnumber = function(port, _proto, _state)
 	local port_table, state_table
 	local proto = _proto or "tcp"
@@ -33,6 +45,14 @@ portnumber = function(port, _proto, _state)
 	end
 end
 
+--- The service argument is either a string or a table of strings which are
+-- interpreted as service names (e.g. "http", "https", "smtp" or "ftp")
+-- against which the script should run. These service names are determined
+-- by Nmap's version scan or (if no version scan information is available)
+-- the service assigned to the port in nmap-services  (e.g. "http" for TCP
+-- port 80). 
+-- @param service Service name or a list of names to run against.
+-- @return Function for the portrule.
 service = function(service, _proto, _state)
 	local service_table, state_table
 	local state = _state or {"open", "open|filtered"}
@@ -65,6 +85,13 @@ service = function(service, _proto, _state)
 	end
 end
 
+--- Run the script if either the port or service is available. This is
+-- a combination of shortport.portnumber and shortport.service, since
+-- many scripts explicitly try to run against the well-known ports,
+-- but want also to run against any other port which was discovered to
+-- run the named service.
+-- @usage portrule = shortport.port_or_service(22,"ssh"). 
+-- @return Function for the portrule.
 port_or_service = function(_port, _service, proto, _state)
 	local state = _state or {"open", "open|filtered"}
 	local state_table

nselib/stdnse.lua

@@ -1,4 +1,5 @@
--- See nmaps COPYING for licence
+--- Standard Nmap Engine functions.
+--@copyright See nmaps COPYING for licence
 
 local assert = assert;
 local tonumber = tonumber;
@@ -7,6 +8,12 @@ local nmap = require"nmap";
 
 module(... or "stdnse");
 
+--- Prints debug information according with verbosity <i>level</i>
+-- formatted using Lua's standard string.format function.
+--@param level Optional argument for verbosity.
+--@param fmt Format string according to string.format specifiers.
+--@param ... Arguments to format.
+--@see string.format
 print_debug = function(level, fmt, ...)
   local verbosity = tonumber(level);
   if verbosity then
@@ -16,16 +23,23 @@ print_debug = function(level, fmt, ...)
   end
 end
 
--- Concat the contents of the parameter list,
--- separated by the string delimiter (just like in perl)
--- example: strjoin(", ", {"Anna", "Bob", "Charlie", "Dolores"})
+--- Concat the contents of the parameter list. Each string is
+-- separated by the string delimiter (just like in perl).
+-- Example: strjoin(", ", {"Anna", "Bob", "Charlie", "Dolores"})
+-- --> "Anna, Bob, Charlie, Dolores"
+--@param delimiter String to delimit each element of the list.
+--@param list Array of strings to concatenate.
+--@return Concatenated string.
 function strjoin(delimiter, list)
   return concat(list, delimiter);
 end
 
--- Split text into a list consisting of the strings in text,
+--- Split text into a list consisting of the strings in text,
 -- separated by strings matching delimiter (which may be a pattern). 
--- example: strsplit(",%s*", "Anna, Bob, Charlie,Dolores")
+-- example: strsplit(",%s*", "Anna, Bob, Charlie, Dolores")
+--@param delimiter String which delimits the split strings.
+--@param text String to split.
+--@return List of strings.
 function strsplit(delimiter, text)
   local list, pos = {}, 1;
 
@@ -44,24 +58,16 @@ function strsplit(delimiter, text)
   return list;
 end
 
--- Generic buffer implementation using lexical closures
---
--- Pass make_buffer a socket and a separator lua pattern [1].
---
--- Returns a function bound to your provided socket with behaviour identical
--- to receive_lines() except it will return AT LEAST ONE [2] and AT MOST ONE
--- "line" at a time.
---
--- [1] Use the pattern "\r?\n" for regular newlines
--- [2] Except where there is trailing "left over" data not terminated by a
---     pattern (in which case you get the data anyways)
--- [3] The data is returned WITHOUT the pattern/newline on the end.
--- [4] Empty "lines" are returned as "". With the pattern in [1] you will
---     receive a "" for each newline in the stream.
--- [5] Errors/EOFs are delayed until all "lines" have been processed.
---
--- -Doug, June, 2007
-
+--- This function operates on a socket attempting to read data. It separates
+-- the data by sep and, for each invocation, returns a piece of the
+-- separated data. Typically this is used to iterate over the lines of
+-- data received from a socket (sep = "\r?\n"). The returned string does
+-- not include the separator. It will return the final data even if it is
+-- not followed by the separator. Once an error or EOF is reached, it
+-- returns nil, msg. msg is what is returned by nmap.receive_lines(). 
+-- @param socket Socket for the buffer.
+-- @param sep Separator for the buffered reads.
+-- @return Data from socket reads.
 function make_buffer(socket, sep)
   local point, left, buffer, done, msg = 1, "";
   local function self()
@@ -120,17 +126,26 @@ do
     f = "1111"
   };
 
+--- Converts the given number, n, to a string in a binary number format.
+--@param n Number to convert.
+--@return String in binary format.
   function tobinary(n)
     assert(tonumber(n), "number expected");
     return (("%x"):format(n):gsub("%w", t):gsub("^0*", ""));
   end
 end
 
+--- Converts the given number, n, to a string in an octal number format.
+--@param n Number to convert.
+--@return String in octal format.
 function tooctal(n)
   assert(tonumber(n), "number expected");
   return ("%o"):format(n)
 end
 
+--- Converts the given number, n, to a string in a hexidecimal number format.
+--@param n Number to convert.
+--@return String in hexidecimal format.
 function tohex(n)
   assert(tonumber(n), "number expected");
   return ("%x"):format(n);

nselib/strbuf.lua

@@ -1,4 +1,5 @@
--- license = "See nmaps COPYING for license"
+--- String Buffer Facilities
+--@copyright See nmaps COPYING for license
 
 -- DEPENDENCIES --
 
@@ -34,8 +35,17 @@ module(... or "strbuf");
 	strbuf.clear(buf)
 --]]
 
+--- Dumps the string buffer as a string.
+--@name dump
+--@class function
+--@param sbuf String buffer to dump.
+--@param delimiter String to separate the buffer's contents.
+--@return Concatenated string result.
 dump = concat;
 
+--- Appends the string s to the buffer, sbuf.
+--@param sbuf String buffer.
+--@param s String to append.
 function concatbuf(sbuf, s)
   if type(s) == "string" then
     sbuf[#sbuf+1] = s;
@@ -49,6 +59,11 @@ function concatbuf(sbuf, s)
   return sbuf;
 end
 
+--- Determines if the two buffers are equal. Two buffers are equal
+-- if they are the same or if they have equivalent contents.
+--@param sbuf1 String buffer one.
+--@param sbuf2 String buffer two.
+--@return boolean true if equal, false otherwise.
 function eqbuf(sbuf1, sbuf2)
   if getmetatable(sbuf1) ~= getmetatable(sbuf2) then
     error("one or more operands is not a string buffer", 2);
@@ -64,12 +79,18 @@ function eqbuf(sbuf1, sbuf2)
   end
 end
 
+--- Clears the string buffer.
+--@param sbuf String buffer.
 function clear(sbuf)
   for k in pairs(sbuf) do
     sbuf[k] = nil;
   end
 end
 
+--- Returns the result of the buffer as a string. The delimiter used
+-- is a newline.
+--@param sbuf String buffer.
+--@return String made from concatenating the buffer.
 function tostring(sbuf)
   return concat(sbuf, "\n");
 end
@@ -81,6 +102,12 @@ local mt = {
   __index = _M,
 };
 
+--- Create a new string buffer. The equals and tostring operators for String
+-- buffers are overloaded to be strbuf.eqbuf and strbuf.tostring respectively.
+-- All functions in strbuf can be accessed by a String buffer using the self
+-- calling mechanism in Lua (e.g. strbuf:dump(...)).
+--@param ... Strings to add to the buffer initially.
+--@return String buffer.
 function new(...)
   return setmetatable({...}, mt);
 end

nselib/tab.lua

@@ -1,13 +1,13 @@
--- See nmaps COPYING for license
-module(... or "tab" ,package.seeall)
+--- Provide NSE scripts with a way to output structured tables similar to
+-- NmapOutputTable.cc.
+--@copyright See nmaps COPYING for license
 
---[[ Provide NSE scripts with a way to output structured tables similar to
-     NmapOutputTable.cc. See end for an example on how to use it. --]]
+module(... or "tab",package.seeall)
 
 require('strbuf')
 
---[[ Create and return a new table with a number of columns equal to col and
-     the row counter set to 1 --]]
+--- Create and return a new table with a number of columns equal to col and
+-- the row counter set to 1.
 function new(cols)
 	assert(cols > 0)
 	local table ={}
@@ -18,9 +18,9 @@ function new(cols)
 	return table
 end
 
---[[ Add a new string item (v) in a previously initialised table (t)
-     at column position 'c'. The data will be added to the current 
-     row, if nextrow() hasn't been called yet that will be row 1 --]]
+--- Add a new string item (v) in a previously initialised table (t)
+-- at column position 'c'. The data will be added to the current
+-- row, if nextrow() hasn't been called yet that will be row 1.
 function add(t, c, v)
 	assert(t)
 	assert(v)
@@ -41,19 +41,19 @@ function add(t, c, v)
 	return true
 end
 
---[[ Move on to the next row in the table. If this is not called
-     then previous column values will be over-written by subsequent
-     values. --]]
+--- Move on to the next row in the table. If this is not called
+-- then previous column values will be over-written by subsequent
+-- values.
 function nextrow(t)
 	assert(t)
 	assert(t['rows'])
 	t['rows'] = t['rows'] + 1
 end
 
---[[ Once items have been added to a table, call this to return a
-     string which contains an equally spaced table. Number of spaces 
-     is based on the largest element of a column with an additional
-     two spaces for padding --]]
+--- Once items have been added to a table, call this to return a
+-- string which contains an equally spaced table. Number of spaces 
+-- is based on the largest element of a column with an additional
+-- two spaces for padding.
 function dump(t)
 	assert(t)
 	assert(t['rows'])

nselib/unpwdb.lua

@@ -2,7 +2,7 @@
 
 module(... or "unpwdb", package.seeall)
 
----- Username/Password DB Library
+--- Username/Password DB Library.
 --
 -- usernames() - Returns a closure which returns a new username with every call
 -- until the username list is exhausted (in which case it returns nil)

nselib/url.lua

@@ -1,3 +1,5 @@
+--- URI parsing, composition and relative URL resolution.
+
 --[[
 
 URI parsing, composition and relative URL resolution