Proofread and update documentation of pop3, shortport, snmp, ssh1, ssh2,

strbuf, tab, unpwdb, and url.

nselib/pop3.lua

@@ -24,9 +24,9 @@ err = {
 }
 
 ---
--- Check a POP3 response for "+OK".
---@param line First line returned from an POP3 request.
---@return Found "+OK" string or nil.
+-- Check a POP3 response for <code>"+OK"</code>.
+-- @param line First line returned from an POP3 request.
+-- @return The string <code>"+OK"</code> if found or <code>nil</code> otherwise.
 function stat(line)
    return string.match(line, "+OK")
 end
@@ -34,11 +34,12 @@ end
 
 
 ---
--- Try to log in using USER/PASS commands.
---@param socket Socket connected to POP3 server.
---@param user User string.
---@param pw Password string.
---@return Success as boolean and error code as in err table.
+-- Try to log in using the <code>USER</code>/<code>PASS</code> commands.
+-- @param socket Socket connected to POP3 server.
+-- @param user User string.
+-- @param pw Password string.
+-- @return Status (true or false).
+-- @return Error code if status is false.
 function login_user(socket, user, pw)
    socket:send("USER " .. user .. "\r\n")
    status, line = socket:receive_lines(1)
@@ -54,11 +55,12 @@ end
 
 
 ---
--- Try to login using AUTH command using SASL/Plain method.
---@param socket Socket connected to POP3 server.
---@param user User string.
---@param pw Password string.
---@return Success as boolean and error code as in err table.
+-- Try to login using the the <code>AUTH</code> command using SASL/Plain method.
+-- @param socket Socket connected to POP3 server.
+-- @param user User string.
+-- @param pw Password string.
+-- @return Status (true or false).
+-- @return Error code if status is false.
 function login_sasl_plain(socket, user, pw)
    
    local auth64 = base64.enc(user .. "\0" .. user .. "\0" .. pw)
@@ -74,11 +76,12 @@ function login_sasl_plain(socket, user, pw)
 end
 
 ---
--- Try to login using AUTH command using SASL/Login method.
---@param user User string.
---@param pw Password string.
---@param pw String containing password to login.
---@return Success as boolean and error code as in err table.
+-- Try to login using the <code>AUTH</code> command using SASL/Login method.
+-- @param user User string.
+-- @param pw Password string.
+-- @param pw String containing password to login.
+-- @return Status (true or false).
+-- @return Error code if status is false.
 function login_sasl_login(socket, user, pw)
 
    local user64 = base64.enc(user)
@@ -112,12 +115,13 @@ function login_sasl_login(socket, user, pw)
 end
 
 ---
--- Try to login using APOP command.
---@param socket Socket connected to POP3 server.
---@param user User string.
---@param pw Password string.
---@param challenge String containing challenge from POP3 server greeting.
---@return Success as boolean and error code as in err table.
+-- Try to login using the <code>APOP</code> command.
+-- @param socket Socket connected to POP3 server.
+-- @param user User string.
+-- @param pw Password string.
+-- @param challenge String containing challenge from POP3 server greeting.
+-- @return Status (true or false).
+-- @return Error code if status is false.
 function login_apop(socket, user, pw, challenge)
    if type(challenge) ~= "string" then return false, err.informationMissing end
 
@@ -134,10 +138,10 @@ function login_apop(socket, user, pw, challenge)
 end
 
 ---
--- Asks POP3 server for capabilities
---@param host Host to be queried.
---@param port Port to connect to.
---@return Table containing capabilities.
+-- Asks a POP3 server for capabilities
+-- @param host Host to be queried.
+-- @param port Port to connect to.
+-- @return Table containing capabilities.
 function capabilities(host, port)
    local socket = nmap.new_socket()
    local capas = {}
@@ -178,11 +182,12 @@ function capabilities(host, port)
 end
 
 ---
--- Try to login using AUTH command using SASL/CRAM-MD5 method.
---@param socket Socket connected to POP3 server.
---@param user User string.
---@param pw Password string.
---@return Success as boolean and error code as in err table.
+-- Try to login using the <code>AUTH</code> command using SASL/CRAM-MD5 method.
+-- @param socket Socket connected to POP3 server.
+-- @param user User string.
+-- @param pw Password string.
+-- @return Status (true or false).
+-- @return Error code if status is false.
 function login_sasl_crammd5(socket, user, pw)
 
    socket:send("AUTH CRAM-MD5\r\n")

nselib/shortport.lua

@@ -1,5 +1,5 @@
 --- Functions for building short portrules.
--- \n\n
+--
 -- Since portrules are mostly the same for many scripts, this
 -- module provides functions for the most common tests.
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
@@ -9,8 +9,9 @@ module(... or "shortport", package.seeall)
 --- Return a portrule that returns true when given an open port matching a
 -- single port number or a list of port numbers.
 -- @param port A single port number or a list of port numbers.
--- @param _proto The protocol to match against, default "tcp".
--- @param _state A state or list of states to match against, default {"open", "open|filtered"}.
+-- @param _proto The protocol to match against, default <code>"tcp"</code>.
+-- @param _state A state or table of states to match against, default
+-- {<code>"open"</code>, <code>"open|filtered"</code>}.
 -- @return Function for the portrule.
 -- @usage portrule = shortport.portnumber({80, 443})
 portnumber = function(port, _proto, _state)
@@ -46,16 +47,18 @@ portnumber = function(port, _proto, _state)
 end
 
 --- Return a portrule that returns true when given an open port with a
---service name matching a single service name or a list of service
---names.
--- \n\n
--- A service name is something like "http", "https", "smtp", or "ftp".
--- 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). 
+-- service name matching a single service name or a list of service
+-- names.
+--
+-- A service name is something like <code>"http"</code>, <code>"https"</code>,
+-- <code>"smtp"</code>, or <code>"ftp"</code>. 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 <code>nmap-services</code>
+-- (e.g. <code>"http"</code> for TCP port 80). 
 -- @param service Service name or a list of names to run against.
--- @param _proto The protocol to match against, default "tcp".
--- @param _state A state or list of states to match against, default {"open", "open|filtered"}.
+-- @param _proto The protocol to match against, default <code>"tcp"</code>.
+-- @param _state A state or list of states to match against, default
+-- {<code>"open"</code>, <code>"open|filtered"</code>}.
 -- @return Function for the portrule.
 -- @usage portrule = shortport.service("ftp")
 service = function(service, _proto, _state)
@@ -92,17 +95,18 @@ end
 
 --- Return a portrule that returns true when given an open port matching
 -- either a port number or service name.
--- \n\n
--- This function is a combination of the portnumber and service
--- functions. The port and service may be single values or a list of
--- values as in those functions. 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.
+--
+-- This function is a combination of the <code>portnumber</code> and
+-- <code>service</code> functions. The port and service may be single values or
+-- a list of values as in those functions. This function exists because 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"). 
 -- @param _port A single port number or a list of port numbers.
 -- @param _service Service name or a list of names to run against.
--- @param proto The protocol to match against, default "tcp".
--- @param _state A state or list of states to match against, default {"open", "open|filtered"}.
+-- @param proto The protocol to match against, default <code>"tcp"</code>.
+-- @param _state A state or list of states to match against, default
+-- {<code>"open"</code>, <code>"open|filtered"</code>}.
 -- @return Function for the portrule.
 port_or_service = function(_port, _service, proto, _state)
 	local state = _state or {"open", "open|filtered"}

nselib/snmp.lua

@@ -7,8 +7,8 @@ module(... or "snmp",package.seeall)
 
 ---
 -- Encodes an Integer according to ASN.1 basic encoding rules.
---@param val Value to be encoded.
---@return encoded integer.
+-- @param val Value to be encoded.
+-- @return Encoded integer.
 local function encodeInt(val)
    local lsb = 0
    if val > 0 then
@@ -45,8 +45,8 @@ end
 
 ---
 -- Encodes the length part of a ASN.1 encoding triplet.
---@param val Value to be encoded.
---@return encoded length value.
+-- @param val Value to be encoded.
+-- @return Encoded length value.
 local function encodeLength(val)
    if (val >= 128) then
       local valStr = ""
@@ -64,10 +64,10 @@ end
 
 
 ---
--- Encodes a given value according to ASN.1 basic encoding
--- rules for SNMP packet creation.
---@param val Value to be encoded.
---@return encoded value.
+-- Encodes a given value according to ASN.1 basic encoding rules for SNMP
+-- packet creation.
+-- @param val Value to be encoded.
+-- @return Encoded value.
 function encode(val)
    local vtype = type(val)
    if (vtype == 'number') then
@@ -118,11 +118,12 @@ end
 
 
 ---
--- Decodes length part of encoded value according to 
--- ASN.1 basic encoding rules.
---@param encStr Encoded string.
---@param pos Current position in the string.
---@return The position after decoding and the length of the following value.
+-- Decodes length part of encoded value according to ASN.1 basic encoding
+-- rules.
+-- @param encStr Encoded string.
+-- @param pos Current position in the string.
+-- @return The position after decoding.
+-- @return The length of the following value.
 local function decodeLength(encStr, pos)
    local elen
    pos, elen = bin.unpack('C', encStr, pos)
@@ -142,12 +143,12 @@ end
 
 
 ---
--- Decodes an Integer according to ASN.1 basic 
--- encoding rules.
---@param encStr Encoded string.
---@param len Length of integer in bytes.
---@param pos Current position in the string.
---@return The position after decoding and the decoded integer.
+-- Decodes an Integer according to ASN.1 basic encoding rules.
+-- @param encStr Encoded string.
+-- @param len Length of integer in bytes.
+-- @param pos Current position in the string.
+-- @return The position after decoding.
+-- @return The decoded integer.
 local function decodeInt(encStr, len, pos)
    local hexStr
    pos, hexStr = bin.unpack("H" .. len, encStr, pos)
@@ -159,12 +160,12 @@ local function decodeInt(encStr, len, pos)
 end
 
 ---
--- Decodes a sequence according to ASN.1 basic 
--- encoding rules.
---@param encStr Encoded string.
---@param len Length of sequence in bytes.
---@param pos Current position in the string.
---@return The position after decoding and the decoded sequence as a table.
+-- Decodes a sequence according to ASN.1 basic encoding rules.
+-- @param encStr Encoded string.
+-- @param len Length of sequence in bytes.
+-- @param pos Current position in the string.
+-- @return The position after decoding.
+-- @return The decoded sequence as a table.
 local function decodeSeq(encStr, len, pos)
    local seq = {}
    local sPos = 1
@@ -180,11 +181,12 @@ local function decodeSeq(encStr, len, pos)
 end
 
 ---
--- Decodes an SNMP packet or a part of it according 
--- to ASN.1 basic encoding rules.
---@param encStr Encoded string.
---@param pos Current position in the string.
---@return The position after decoding and the decoded value(s).
+-- Decodes an SNMP packet or a part of it according to ASN.1 basic encoding
+-- rules.
+-- @param encStr Encoded string.
+-- @param pos Current position in the string.
+-- @return The position after decoding
+-- @return The decoded value(s).
 function decode(encStr, pos)
    local etype, elen
    pos, etype = bin.unpack("H1", encStr, pos)
@@ -272,11 +274,11 @@ function decode(encStr, pos)
 end
 
 ---
--- Decodes an SNMP packet or a part of it according 
--- to ASN.1 basic encoding rules.
---@param encStr Encoded string.
---@param pos Current position in the string.
---@return The decoded value(s).
+-- Decodes an SNMP packet or a part of it according to ASN.1 basic encoding
+-- rules.
+-- @param encStr Encoded string.
+-- @param pos Current position in the string.
+-- @return The decoded value(s).
 function dec(encStr, pos)
    local result
    local _
@@ -285,10 +287,11 @@ function dec(encStr, pos)
 end
 
 ---
--- Create SNMP packet.
---@param PDU SNMP Protocol Data Unit to be encapsulated in the packet.
---@param version SNMP version, default 0 (SNMP V1).
---@param commStr community string, if not already supplied in registry or as script argument.
+-- Create an SNMP packet.
+-- @param PDU SNMP Protocol Data Unit to be encapsulated in the packet.
+-- @param version SNMP version, default <code>0</code> (SNMP V1).
+-- @param commStr community string, if not already supplied in registry or as
+-- script argument.
 function buildPacket(PDU, version, commStr)
    local comm = nmap.registry.args.snmpcommunity
    if (not comm) then comm = nmap.registry.snmpcommunity end
@@ -305,13 +308,13 @@ end
 
 
 --- 
--- Create SNMP Get Request PDU.
---@param options A table containing the following keys and values:\n
---"reqId": request ID\n
---"err": error\n
---"errIdx": error index
---@param ... Object identifiers to be queried.
---@return Table representing PDU.
+-- Create an SNMP Get Request PDU.
+-- @param options A table containing the following fields:
+-- * <code>"reqId"</code>: Request ID.
+-- * <code>"err"</code>: Error.
+-- * <code>"errIdx"</code>: Error index.
+-- @param ... Object identifiers to be queried.
+-- @return Table representing PDU.
 function buildGetRequest(options, ...)
    if not options then options = {} end
 
@@ -340,13 +343,13 @@ end
 
 
 --- 
--- Create SNMP Get Next Request PDU.
---@param options A table containing the following keys and values:\n
---"reqId": request ID\n
---"err": error\n
---"errIdx": error index
---@param ... Object identifiers to be queried.
---@return Table representing PDU.
+-- Create an SNMP Get Next Request PDU.
+-- @param options A table containing the following fields:
+-- * <code>"reqId"</code>: Request ID.
+-- * <code>"err"</code>: Error.
+-- * <code>"errIdx"</code>: Error index.
+-- @param ... Object identifiers to be queried.
+-- @return Table representing PDU.
 function buildGetNextRequest(options, ...)
    if not options then options = {} end
 
@@ -374,16 +377,17 @@ function buildGetNextRequest(options, ...)
 end
 
 --- 
--- Create SNMP Set Request PDU.
--- \n\n
+-- Create an SNMP Set Request PDU.
+--
 -- Takes one OID/value pair or an already prepared table.
---@param options A table containing the following keys and values:\n
---"reqId": request ID\n
---"err": error\n
---"errIdx": error index
---@param oid Object identifiers of object to be set.
---@param value To which value object should be set. If given a table, use table instead of OID/value pair.
---@return Table representing PDU.
+-- @param options A table containing the following keys and values:
+-- * <code>"reqId"</code>: Request ID.
+-- * <code>"err"</code>: Error.
+-- * <code>"errIdx"</code>: Error index.
+-- @param oid Object identifiers of object to be set.
+-- @param value To which value object should be set. If given a table, use the
+-- table instead of OID/value pair.
+-- @return Table representing PDU.
 function buildSetRequest(options, oid, value)
    if not options then options = {} end
 
@@ -414,8 +418,8 @@ function buildSetRequest(options, oid, value)
 end
 
 --- 
--- Create SNMP Trap PDU
---@return Table representing PDU
+-- Create an SNMP Trap PDU.
+-- @return Table representing PDU
 function buildTrap(enterpriseOid, agentIp, genTrap, specTrap, timeStamp)
    local req = {}
    req._snmp = 'A4'
@@ -442,16 +446,16 @@ function buildTrap(enterpriseOid, agentIp, genTrap, specTrap, timeStamp)
 end
 
 --- 
--- Create SNMP Get Response PDU.
--- \n\n
+-- Create an SNMP Get Response PDU.
+--
 -- Takes one OID/value pair or an already prepared table.
---@param options A table containing the following keys and values:\n
---"reqId": request ID\n
---"err": error\n
---"errIdx": error index
---@param oid Object identifiers of object to be sent back.
---@param value To which value object or returned object. If given a table, use table instead of OID/value pair.
---@return Table representing PDU.
+-- @param options A table containing the following keys and values:
+-- * <code>"reqId"</code>: Request ID.
+-- * <code>"err"</code>: Error.
+-- * <code>"errIdx"</code>: Error index.
+-- @param oid Object identifiers of object to be sent back.
+-- @param value If given a table, use the table instead of OID/value pair.
+-- @return Table representing PDU.
 function buildGetResponse(options, oid, value) 
    if not options then options = {} end
 
@@ -485,8 +489,9 @@ end
 
 --- 
 -- Transforms a string into an object identifier table.
---@param oidStr Object identifier as string, for example "1.3.6.1.2.1.1.1.0".
---@return Table representing OID.
+-- @param oidStr Object identifier as string, for example
+-- <code>"1.3.6.1.2.1.1.1.0"</code>.
+-- @return Table representing OID.
 function str2oid(oidStr)
    local oid = {}
    for n in string.gmatch(oidStr, "%d+") do
@@ -498,8 +503,8 @@ end
 
 ---
 -- Transforms a table representing an object identifier to a string.
---@param oid Object identifier table.
---@return OID string.
+-- @param oid Object identifier table.
+-- @return OID string.
 function oid2str(oid)
    if (type(oid) ~= "table") then return 'invalid oid' end
    return table.concat(oid, '.')
@@ -507,8 +512,8 @@ end
 
 ---
 -- Transforms a table representing an IP to a string.
---@param ip IP table.
---@return IP string.
+-- @param ip IP table.
+-- @return IP string.
 function ip2str(ip)
    if (type(ip) ~= "table") then return 'invalid ip' end
    return table.concat(ip, '.')
@@ -517,8 +522,8 @@ end
 
 ---
 -- Transforms a string into an IP table.
---@param ipStr IP as string.
---@return Table representing IP.
+-- @param ipStr IP as string.
+-- @return Table representing IP.
 function str2ip(ipStr)
    local ip = {}
    for n in string.gmatch(ipStr, "%d+") do
@@ -531,8 +536,8 @@ end
 
 ---
 -- Fetches values from a SNMP response.
---@param resp SNMP Response (will be decoded if necessary).
---@return Table with all decoded responses and their OIDs.
+-- @param resp SNMP Response (will be decoded if necessary).
+-- @return Table with all decoded responses and their OIDs.
 function fetchResponseValues(resp)
    if (type(resp) == "string") then
       local _
@@ -576,9 +581,9 @@ end
 
 
 ---
--- Fetches first value from a SNMP response.
---@param response SNMP Response (will be decoded if necessary).
---@return First decoded value of the response.
+-- Fetches the first value from a SNMP response.
+-- @param response SNMP Response (will be decoded if necessary).
+-- @return First decoded value of the response.
 function fetchFirst(response)
    local result = fetchResponseValues(response)
    if type(result) == "table" and result[1] and result[1][1] then return result[1][1]

nselib/ssh1.lua

@@ -1,5 +1,5 @@
 --- Functions for the SSH-1 protocol.
--- \n\n
+--
 -- This module also contains functions for formatting key fingerprints.
 -- @author Sven Klemm <sven@c3d2.de>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
@@ -12,11 +12,13 @@ local math = require "math"
 local stdnse = require "stdnse"
 local openssl = require "openssl"
 
---- Fetch a SSH-1 host key.
---@param host Nmap host table.
---@param port Nmap port table.
---@return A table with the following keys: "exp", "mod", "bits", "key_type",
---"fp_input", "full_key", "algorithm", and "fingerprint".
+--- Fetch an SSH-1 host key.
+-- @param host Nmap host table.
+-- @param port Nmap port table.
+-- @return A table with the following fields: <code>exp</code>,
+-- <code>mod</code>, <code>bits</code>, <code>key_type</code>,
+-- <code>fp_input</code>, <code>full_key</code>, <code>algorithm</code>, and
+-- <code>fingerprint</code>.
 fetch_host_key = function(host, port)
   local socket = nmap.new_socket()
   local status
@@ -70,12 +72,18 @@ fetch_host_key = function(host, port)
 end
 
 --- Format a key fingerprint in hexadecimal.
+-- @param fingerprint Key fingerprint.
+-- @param algorithm Key algorithm.
+-- @param bits Key size in bits.
 fingerprint_hex = function( fingerprint, algorithm, bits )
   fingerprint = stdnse.tohex(fingerprint,{separator=":",group=2})
   return ("%d %s (%s)"):format( bits, fingerprint, algorithm )
 end
 
 --- Format a key fingerprint in Bubble Babble.
+-- @param fingerprint Key fingerprint.
+-- @param algorithm Key algorithm.
+-- @param bits Key size in bits.
 fingerprint_bubblebabble = function( fingerprint, algorithm, bits )
   local vowels = {'a','e','i','o','u','y'}
   local consonants = {'b','c','d','f','g','h','k','l','m','n','p','r','s','t','v','z','x'}
@@ -109,8 +117,11 @@ fingerprint_bubblebabble = function( fingerprint, algorithm, bits )
 end
 
 --- Format a key fingerprint into a visual ASCII art representation.
--- \n\n
+--
 -- Ported from http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/src/usr.bin/ssh/key.c.
+-- @param fingerprint Key fingerprint.
+-- @param algorithm Key algorithm.
+-- @param bits Key size in bits.
 fingerprint_visual = function( fingerprint, algorithm, bits )
   local i,j,field,characters,input,fieldsize_x,fieldsize_y,s
   fieldsize_x, fieldsize_y = 17, 9

nselib/ssh2.lua

@@ -16,8 +16,8 @@ transport = {}
 local SSH2
 
 --- Pack a multiprecision integer for sending.
---@param bn openssl bignum.
---@return packed multiprecision integer.
+-- @param bn <code>openssl</code> bignum.
+-- @return Packed multiprecision integer.
 transport.pack_mpint = function( bn )
   local bytes, packed
   bytes = bn:num_bytes()
@@ -30,8 +30,8 @@ transport.pack_mpint = function( bn )
 end
 
 --- Build an SSH-2 packet.
---@param payload payload of the packet.
---@return packet to send on the wire.
+-- @param payload Payload of the packet.
+-- @return Packet to send on the wire.
 transport.build = function( payload )
   local packet_length, padding_length
   padding_length = 8 - ( (payload:len() + 1 + 4 ) % 8 )
@@ -40,8 +40,8 @@ transport.build = function( payload )
 end
 
 --- Extract the payload from a received SSH-2 packet.
---@param packet received SSH2 packet.
---@return payload of the SSH2 packet.
+-- @param packet Peceived SSH-2 packet.
+-- @return Payload of the SSH-2 packet.
 transport.payload = function( packet )
   local packet_length, padding_length, payload_length, payload, offset
   offset, packet_length, padding_length = bin.unpack( ">Ic", packet )
@@ -50,12 +50,12 @@ transport.payload = function( packet )
   return payload
 end
 
---- Build kexdh_init packet.
+--- Build a <code>kexdh_init</code> packet.
 transport.kexdh_init = function( e )
   return bin.pack( ">cA", SSH2.SSH_MSG_KEXDH_INIT, transport.pack_mpint( e ) )
 end
 
---- Build kex_init packet.
+--- Build a <code>kex_init</code> packet.
 transport.kex_init = function( cookie, options )
   options = options or {}
   kex_algorithms = "diffie-hellman-group1-sha1"
@@ -75,8 +75,8 @@ transport.kex_init = function( cookie, options )
   return payload
 end
 
---- Parse kexinit package.
--- \n\n
+--- Parse a <code>kexinit</code> package.
+--
 -- Returns an empty table in case of an error
 transport.parse_kex_init = function( payload ) 
   local _, offset, msg_code, parsed, fields, fieldname
@@ -102,10 +102,12 @@ end
 
 
 --- Fetch an SSH-2 host key.
---@param host Nmap host table.
---@param port Nmap port table.
---@param key_type key type to fetch.
---@return table containing the key and fingerprint.
+-- @param host Nmap host table.
+-- @param port Nmap port table.
+-- @param key_type key type to fetch.
+-- @return A table with the following fields: <code>key</code>,
+-- <code>key_type</code>, <code>fp_input</code>, <code>bits</code>,
+-- <code>full_key</code>, <code>algorithm</code>, and <code>fingerprint</code>.
 fetch_host_key = function( host, port, key_type )
   local socket = nmap.new_socket()
   local status

nselib/strbuf.lua

@@ -1,38 +1,39 @@
---- String Buffer facilities.
--- \n\n
+--- String buffer facilities.
+--
 -- Lua's string operations are very flexible and offer an easy-to-use way to
--- manipulate strings. Concatenation using the .. operator is such an
--- operation. The drawback of the built-in API however is the way it handles
+-- manipulate strings. Concatenation using the <code>..</code> operator is such
+-- an operation. The drawback of the built-in API however is the way it handles
 -- concatenation of many string values. Since strings in Lua are immutable
--- values, each time you concatenate two strings both get copied into the result
--- string.
--- \n\n
--- The strbuf module offers a workaround for this problem, while
+-- values, each time you concatenate two strings both get copied into the
+-- result string.
+--
+-- The <code>strbuf</code> module offers a workaround for this problem, while
 -- maintaining the nice syntax. This is accomplished by overloading the
--- concatenation operator (..) the equality operator (==) and the tostring
--- operator. By overloading these operators, we reduce the overhead of using a
--- string buffer instead of a plain string to wrap the first literal string
--- assigned to a variable inside a strbuf.new() call. Afterwards you can append
--- to the string buffer, or compare two string buffers for equality just as you
--- would do with normal strings.
--- \n\n
--- When looking at the details there are some more
--- restrictions/oddities: The concatenation operator requires its left-hand
--- value to be a string buffer. Therefore, if you want to prepend a string to a
--- given string buffer you have to create a new string buffer out of the string
--- you want to prepend. The string buffer's tostring operator concatenates the
--- strings inside the buffer using newlines by default, since this appears to be
--- the separator used most often.
--- \n\n
--- Example usage:\n
--- local buf = strbuf.new()\n
--- local buf2 = strbuf.new('hello')\n
--- buf = buf .. 'string'\n
--- buf = buf .. 'data'\n
--- print(buf)                   -- default separator is a new line\n
--- print(strbuf.dump(buf))      -- no separator\n
--- print(strbuf.dump(buf, ' ')) -- separated by spaces\n
+-- concatenation operator (<code>..</code>), the equality operator (<code>==</code>) and the <code>tostring</code>
+-- operator. A string buffer is created by passing a string to
+-- <code>strbuf.new()</code>. Afterwards you can append to the string buffer,
+-- or compare two string buffers for equality just as you would do with normal
+-- strings.
+--
+-- When looking at the details there are some more restrictions/oddities: The
+-- concatenation operator requires its left-hand value to be a string buffer.
+-- Therefore, if you want to prepend a string to a given string buffer you have
+-- to create a new string buffer out of the string you want to prepend. The
+-- string buffer's <code>tostring</code> operator concatenates the strings
+-- inside the buffer using newlines by default, since this appears to be the
+-- separator used most often.
+--
+-- Example usage:
+-- <code>
+-- local buf = strbuf.new()
+-- local buf2 = strbuf.new('hello')
+-- buf = buf .. 'string'
+-- buf = buf .. 'data'
+-- print(buf)                   -- default separator is a newline
+-- print(strbuf.dump(buf))      -- no separator
+-- print(strbuf.dump(buf, ' ')) -- separated by spaces
 -- strbuf.clear(buf)
+-- </code>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 -- DEPENDENCIES --
@@ -54,19 +55,20 @@ module(... or "strbuf");
 -- e.g. for i = 1, 10 do s = s..i end
 
 --- Dumps the string buffer as a string.
--- \n\n
+--
 -- The second parameter is used as a delimiter between the strings stored inside
--- strbuf.
---@name dump
---@class function
---@param sbuf String buffer to dump.
---@param delimiter String to separate the buffer's contents.
---@return Concatenated string result.
+-- the string buffer.
+-- @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.
+--- Appends a string to a string buffer.
+-- @param sbuf String buffer.
+-- @param s String to append.
+-- @return <code>sbuf</code>.
 function concatbuf(sbuf, s)
   if type(s) == "string" then
     sbuf[#sbuf+1] = s;
@@ -80,11 +82,11 @@ function concatbuf(sbuf, s)
   return sbuf;
 end
 
---- Determines if the two buffers are equal. Two buffers are equal
+--- Determines if the two string 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.
+-- @param sbuf1 String buffer one.
+-- @param sbuf2 String buffer two.
+-- @return 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);
@@ -100,18 +102,17 @@ function eqbuf(sbuf1, sbuf2)
   end
 end
 
---- Clears the string buffer.
---@param sbuf String buffer.
+--- Clears a 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.
+--- Returns the string 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
@@ -124,12 +125,13 @@ local mt = {
 };
 
 --- Create a new string buffer.
--- \n\n
+--
 -- The optional arguments are added to the string buffer. The result of adding
--- non-strings is undefined. The equals and tostring operators for string
--- buffers are overloaded to be strbuf.eqbuf and strbuf.tostring respectively.
---@param ... Strings to add to the buffer initially.
---@return String buffer.
+-- non-strings is undefined. The <code>equals</code> and <code>tostring</code>
+-- operators for string buffers are overloaded to be <code>eqbuf</code> and
+-- <code>tostring</code> respectively.
+-- @param ... Strings to add to the buffer initially.
+-- @return String buffer.
 function new(...)
   return setmetatable({...}, mt);
 end

nselib/tab.lua

@@ -1,25 +1,28 @@
 --- Arrange output into tables.
--- \n\n
+--
 -- This module provides NSE scripts with a way to output structured tables
--- similar to NmapOutputTable.cc.
--- \n\n
--- Example usage:\n
--- local t = tab.new(2)\n
--- tab.add(t, 1, 'A1')\n
--- tab.add(t, 2, 'A2')\n
--- tab.nextrow(t)\n
--- tab.add(t, 1, 'BBBBBBBBB1')\n
--- tab.add(t, 2, 'BBB2')\n
+-- similar to what <code>NmapOutputTable.cc</code> provides.
+--
+-- Example usage:
+-- <code>
+-- local t = tab.new(2)
+-- tab.add(t, 1, 'A1')
+-- tab.add(t, 2, 'A2')
+-- tab.nextrow(t)
+-- tab.add(t, 1, 'BBBBBBBBB1')
+-- tab.add(t, 2, 'BBB2')
 -- tab.dump(t)
+-- </code>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 module(... or "tab",package.seeall)
 
 require('strbuf')
 
---- Create and return a new table with a number of columns equal to cols and
+--- Create and return a new table with a given number of columns and
 -- the row counter set to 1.
--- @param cols the number of columns the table will hold.
+-- @param cols The number of columns the table will hold.
+-- @return A new table.
 function new(cols)
 	assert(cols > 0)
 	local table ={}
@@ -31,13 +34,12 @@ function new(cols)
 end
 
 --- Add a new string item to a table at a given column position.
--- \n\n
--- The item will be added to the current row. If nextrow hasn't been called yet
--- that will be row 1.
 --
--- @param t the table.
--- @param v the string to add.
--- @param c the column position at which to add the item.
+-- The item will be added to the current row. If <code>nextrow</code> hasn't
+-- been called yet that will be row 1.
+-- @param t The table.
+-- @param v The string to add.
+-- @param c The column position at which to add the item.
 function add(t, c, v)
 	assert(t)
 	assert(v)
@@ -59,11 +61,11 @@ function add(t, c, v)
 end
 
 --- Add a complete row to the table and move on to the next row.
--- \n\n
--- Calls add for each argument starting with the second argument
--- and after that calls nextrow.
--- @param t the table.
--- @param ... the elements to add to the row.
+--
+-- Calls <code>add</code> for each argument starting with the second argument
+-- and after that calls <code>nextrow</code>.
+-- @param t The table.
+-- @param ... The elements to add to the row.
 function addrow(t, ...)
 	for i=1, arg['n'] do
 		add( t, i, tostring(arg[i]) )
@@ -74,7 +76,7 @@ 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.
--- @param t the table.
+-- @param t The table.
 function nextrow(t)
 	assert(t)
 	assert(t['rows'])
@@ -82,10 +84,10 @@ function nextrow(t)
 end
 
 --- Return a formatted string representation of the table.
--- \n\n
+--
 -- The number of spaces in a column is based on the largest element in the
 -- column with an additional two spaces for padding.
--- @param t the table.
+-- @param t The table.
 function dump(t)
 	assert(t)
 	assert(t['rows'])

nselib/unpwdb.lua

@@ -1,19 +1,20 @@
 --- Username/password database library.
--- \n\n
--- The usernames and passwords functions return multiple values for use
--- with exception handling via nmap.new_try().
--- The first value is the boolean success indicator, the second value is
--- the closure.
--- \n\n
--- The closures can take a parameter of "reset" to rewind the list to the
--- beginning.
--- \n\n
+--
+-- The <code>usernames</code> and <code>passwords</code> functions return
+-- multiple values for use with exception handling via
+-- <code>nmap.new_try()</code>. The first value is the Boolean success
+-- indicator, the second value is the closure.
+--
+-- The closures can take an argument of <code>"reset"</code> to rewind the list
+-- to the beginning.
+--
 -- You can select your own username and/or password database to read from with
--- the script arguments userdb and passdb, respectively.  Comments are allowed
--- in these files, prefixed with "#!comment:".  Comments cannot be on the same
--- line as a username or password because this leaves too much ambiguity, e.g.
--- does the password in "mypass  #!comment: blah" contain a space, two spaces,
--- or do they just separate the password from the comment?
+-- the script arguments <code>userdb</code> and <code>passdb</code>,
+-- respectively.  Comments are allowed in these files, prefixed with
+-- <code>"#!comment:"</code>.  Comments cannot be on the same line as a
+-- username or password because this leaves too much ambiguity, e.g. does the
+-- password in <code>"mypass  #!comment: blah"</code> contain a space, two
+-- spaces, or do they just separate the password from the comment?
 --
 -- @author Kris Katterjohn 06/2008
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
@@ -89,14 +90,15 @@ local closure = function(table)
 	end
 end
 
---- Returns the suggested number of seconds to attempt a brute
--- force attack, based on Nmap's timing values (-T4, etc) and whether or not a
+--- Returns the suggested number of seconds to attempt a brute force attack,
+-- based on Nmap's timing values (<code>-T4</code> etc.) and whether or not a
 -- user-defined list is used.
--- \n\n
--- You can use the script argument "notimelimit" to make this function return
--- nil, which means the brute-force should run until the list is empty. If
--- "notimelimit" is not used, be sure to still check for nil return values on
--- the above two functions in case you finish before the time limit is up.
+--
+-- You can use the script argument <code>notimelimit</code> to make this
+-- function return <code>nil</code>, which means the brute-force should run
+-- until the list is empty. If <code>notimelimit</code> is not used, be sure to
+-- still check for <code>nil</code> return values on the above two functions in
+-- case you finish before the time limit is up.
 timelimit = function()
    -- If we're reading from a user-defined username or password list,
    -- we'll give them a timeout 1.5x the default.  If the "notimelimit"
@@ -118,7 +120,8 @@ timelimit = function()
 end
 
 --- Returns a function closure which returns a new username with every call
--- until the username list is exhausted (in which case it returns nil).
+-- until the username list is exhausted (in which case it returns
+-- <code>nil</code>).
 -- @return boolean Status.
 -- @return function The usernames iterator.
 usernames = function()
@@ -136,7 +139,8 @@ usernames = function()
 end
 
 --- Returns a function closure which returns a new password with every call
--- until the password list is exhausted (in which case it returns nil).
+-- until the password list is exhausted (in which case it returns
+-- <code>nil</code>).
 -- @return boolean Status.
 -- @return function The passwords iterator.
 passwords = function()

nselib/url.lua

@@ -40,9 +40,9 @@ local segment_set = make_set {
 
 ---
 -- Protects a path segment, to prevent it from interfering with the
--- url parsing.
--- @param s binary string to be encoded.
--- @return escaped representation of string binary.
+-- URL parsing.
+-- @param s Binary string to be encoded.
+-- @return Escaped representation of string.
 local function protect_segment(s)
 	return string.gsub(s, "([^A-Za-z0-9_])", function (c)
 		if segment_set[c] then return c
@@ -52,9 +52,9 @@ end
 
 ---
 -- Builds a path from a base path and a relative path
--- @param base_path a base path.
--- @param relative_path a relative path.
--- @return corresponding absolute path.
+-- @param base_path A base path.
+-- @param relative_path A relative path.
+-- @return The corresponding absolute path.
 -----------------------------------------------------------------------------
 local function absolute_path(base_path, relative_path)
     if string.sub(relative_path, 1, 1) == "/" then return relative_path end
@@ -82,8 +82,8 @@ end
 
 ---
 -- Encodes a string into its escaped hexadecimal representation.
--- @param s binary string to be encoded.
--- @return escaped representation of string binary.
+-- @param s Binary string to be encoded.
+-- @return Escaped representation of string.
 -----------------------------------------------------------------------------
 function escape(s)
     return string.gsub(s, "([^A-Za-z0-9_])", function(c)
@@ -93,9 +93,9 @@ end
 
 
 ---
--- Encodes a string into its escaped hexadecimal representation.
--- @param s binary string to be encoded.
--- @return escaped representation of string binary.
+-- Decodes an escaped hexadecimal string.
+-- @param s Hexadecimal-encoded string.
+-- @return Decoded string.
 -----------------------------------------------------------------------------
 function unescape(s)
     return string.gsub(s, "%%(%x%x)", function(hex)
@@ -106,20 +106,25 @@ end
 
 ---
 -- Parses a URL and returns a table with all its parts according to RFC 2396.
--- \n\n
--- The following grammar describes the names given to the URL parts.\n
--- <url> ::= <scheme>://<authority>/<path>;<params>?<query>#<fragment>\n
--- <authority> ::= <userinfo>@<host>:<port>\n
--- <userinfo> ::= <user>[:<password>]\n
--- <path> :: = {<segment>/}<segment>\n
--- \n\n
--- Obs: the leading '/' in {/<path>} is considered part of <path>.
--- @param url uniform resource locator of request
--- @param default table with default values for each field
--- @return a table with the following fields, where RFC naming conventions have
+--
+-- The following grammar describes the names given to the URL parts.
+-- <code>
+-- <url> ::= <scheme>://<authority>/<path>;<params>?<query>#<fragment>
+-- <authority> ::= <userinfo>@<host>:<port>
+-- <userinfo> ::= <user>[:<password>]
+-- <path> :: = {<segment>/}<segment>
+-- </code>
+--
+-- The leading <code>/</code> in <code>/<path></code> is considered part of
+-- <code><path></code>.
+-- @param url URL of request.
+-- @param default Table with default values for each field.
+-- @return A table with the following fields, where RFC naming conventions have
 --   been preserved:
---     scheme, authority, userinfo, user, password, host, port,
---     path, params, query, fragment.
+--     <code>scheme</code>, <code>authority</code>, <code>userinfo</code>,
+--     <code>user</code>, <code>password</code>, <code>host</code>,
+--     <code>port</code>, <code>path</code>, <code>params</code>,
+--     <code>query</code>, and <code>fragment</code>.
 -----------------------------------------------------------------------------
 function parse(url, default)
     -- initialize default parameters
@@ -171,10 +176,10 @@ end
 
 ---
 -- Rebuilds a parsed URL from its components.
--- \n\n
+--
 -- Components are protected if any reserved or unallowed characters are found.
--- @param parsed parsed URL, as returned by parse.
--- @return a string with the corresponding URL.
+-- @param parsed Parsed URL, as returned by parse.
+-- @return A string with the corresponding URL.
 -----------------------------------------------------------------------------
 function build(parsed)
     local ppath = parse_path(parsed.path or "")
@@ -202,10 +207,10 @@ function build(parsed)
 end
 
 ---
--- Builds a absolute URL from a base and a relative URL according to RFC 2396.
--- @param base_url a base URL.
--- @param relative_url a relative URL.
--- @return corresponding absolute URL.
+-- Builds an absolute URL from a base and a relative URL according to RFC 2396.
+-- @param base_url A base URL.
+-- @param relative_url A relative URL.
+-- @return The corresponding absolute URL.
 -----------------------------------------------------------------------------
 function absolute(base_url, relative_url)
     if type(base_url) == "table" then
@@ -241,8 +246,8 @@ end
 
 ---
 -- Breaks a path into its segments, unescaping the segments.
--- @param path a path to break.
--- @return a table with one entry per segment.
+-- @param path A path to break.
+-- @return A table with one entry per segment.
 -----------------------------------------------------------------------------
 function parse_path(path)
 	local parsed = {}
@@ -259,9 +264,9 @@ end
 
 ---
 -- Builds a path component from its segments, escaping protected characters.
--- @param parsed path segments.
--- @param unsafe if true, segments are not protected before path is built.
--- @return corresponding path string
+-- @param parsed Path segments.
+-- @param unsafe If true, segments are not protected before path is built.
+-- @return The corresponding path string
 -----------------------------------------------------------------------------
 function build_path(parsed, unsafe)
 	local path = ""
@@ -291,14 +296,14 @@ end
 
 ---
 -- Breaks a query string into name/value pairs.
--- \n\n
--- This function takes a <query-string> of the form name1=value1&name2=value2...
+--
+-- This function takes a <code><query></code> of the form
+-- <code>"name1=value1&name2=value2"</code>
 -- and returns a table containing the name-value pairs, with the name as the key
--- and the value as its associated value. The table corresponding to the above
--- <query-string> would have two entries: table["name1"]="value1" and
--- table["name2"]="value2".
--- @param query string (name=value&name=value ...).
--- @return table where name=value is table['name'] = value.
+-- and the value as its associated value.
+-- @param query Query string.
+-- @return A table of name-value pairs following the pattern
+-- <code>table["name"]</code> = <code>value</code>.
 -----------------------------------------------------------------------------
 function parse_query(query)
 	local parsed = {}
@@ -329,11 +334,12 @@ function parse_query(query)
 end
 
 ---
--- Builds a query string from dictionary based table.
--- \n\n
--- This is the inverse of parse_query.
--- @param query dictionary table where table['name'] = value.
--- @return query string (name=value&name=value ...)
+-- Builds a query string from a table.
+--
+-- This is the inverse of <code>parse_query</code>.
+-- @param query A dictionary table where <code>table['name']</code> =
+-- <code>value</code>.
+-- @return A query string (like <code>"name=value2&name=value2"</code>).
 -----------------------------------------------------------------------------
 function build_query(query)
 	local qstr = ""