Proofread and update documentation format in base64, bin, bit, comm, datafiles,

and dns.

nselib/base64.lua

@@ -1,4 +1,4 @@
---- Base64 library. Follows RFC4648.
+--- Base64 encoding and decoding. Follows RFC 4648.
 -- @author Philip Pickering <pgpickering@gmail.com>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
@@ -95,7 +95,7 @@ local bunpack = bin.unpack
 local concat = table.concat
 
 ---
--- Encode six bits to a base64 encoded character.
+-- Encode six bits to a Base64-encoded character.
 -- @param bits String of six bits to be encoded.
 -- @return Encoded character.
 local function b64enc6bit(bits)
@@ -110,8 +110,8 @@ end
 
 
 ---
--- Decodes a base64 encoded character into binary digits.
---@param b64byte Single base64 encoded character.
+-- Decodes a Base64-encoded character into a string of binary digits.
+-- @param b64byte A single base64-encoded character.
 -- @return String of six decoded bits.
 local function b64dec6bit(b64byte)
 	local bits = b64dctable[b64byte]
@@ -121,9 +121,9 @@ end
 
 
 ---
--- Encodes a string to base64.
+-- Encodes a string to Base64.
 -- @param bdata Data to be encoded.
---@return Base64 encoded string.
+-- @return Base64-encoded string.
 function enc(bdata)
 	local pos = 1
 	local byte
@@ -152,7 +152,7 @@ end
 
 
 ---
--- Decodes base64 encoded data.
+-- Decodes Base64-encoded data.
 -- @param b64data Base64 encoded data.
 -- @return Decoded data.
 function dec(b64data)

nselib/bin.luadoc

@@ -1,6 +1,5 @@
-
 --- Pack and unpack binary data.
--- \n\n
+--
 -- A problem script authors often face is the necessity of encoding values
 -- into binary data. For example after analyzing a protocol the starting 
 -- point to write a script could be a hex dump, which serves as a preamble
@@ -8,33 +7,33 @@
 -- functionality Lua provides, it's not very convenient. Therefore NSE includes
 -- Binlib, based on lpack (http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/)
 -- by Luiz Henrique de Figueiredo.
--- \n\n
+--
 -- The Binlib functions take a format string to encode and decode binary
 -- data. Packing and unpacking are controlled by the following operator
--- characters:\n
--- * H: hex string
--- * B: bit string
--- * x: null byte
--- * z: zero-terminated string
--- * p: string preceded by 1-byte integer length
--- * P: string preceded by 2-byte integer length
--- * a: string preceded by 4-byte integer length
--- * A: string
--- * f: float
--- * d: double
--- * n: Lua number
--- * c: char (1-byte integer)
--- * C: byte = unsigned char (1-byte unsigned integer)
--- * s: short (2-byte integer)
--- * S: unsigned short (2-byte unsigned integer)
--- * i: int (4-byte integer)
--- * I: unsigned int (4-byte unsigned integer)
--- * l: long (8-byte integer)
--- * L: unsigned long (8-byte unsigned integer)
--- * <: little endian modifier
--- * >: big endian modifier
--- * =: native endian modifier
--- \n\n
+-- characters:
+-- * <code>H</code> hex string
+-- * <code>B</code> bit string
+-- * <code>x</code> null byte
+-- * <code>z</code> zero-terminated string
+-- * <code>p</code> string preceded by 1-byte integer length
+-- * <code>P</code> string preceded by 2-byte integer length
+-- * <code>a</code> string preceded by 4-byte integer length
+-- * <code>A</code> string
+-- * <code>f</code> float
+-- * <code>d</code> double
+-- * <code>n</code> Lua number
+-- * <code>c</code> char (1-byte integer)
+-- * <code>C</code> byte = unsigned char (1-byte unsigned integer)
+-- * <code>s</code> short (2-byte integer)
+-- * <code>S</code> unsigned short (2-byte unsigned integer)
+-- * <code>i</code> int (4-byte integer)
+-- * <code>I</code> unsigned int (4-byte unsigned integer)
+-- * <code>l</code> long (8-byte integer)
+-- * <code>L</code> unsigned long (8-byte unsigned integer)
+-- * <code><</code> little endian modifier
+-- * <code>></code> big endian modifier
+-- * <code>=</code> native endian modifier
+--
 -- Note that the endian operators work as modifiers to all the 
 -- characters following them in the format string.
 
@@ -42,13 +41,13 @@ module "bin"
 
 
 --- Returns a binary packed string.
--- \n\n
--- The format string describes how the parameters (p1, ...) will be interpreted.
--- Numerical values following operators stand for operator repetitions and need
--- an according amount of parameters. Operators expect appropriate parameter
--- types.
--- \n\n
--- Note: on Windows packing of 64 bit values > 2^63 currently
+--
+-- The format string describes how the parameters (<code>p1</code>,
+-- <code>...</code>) will be interpreted. Numerical values following operators
+-- stand for operator repetitions and need an according amount of parameters.
+-- Operators expect appropriate parameter types.
+--
+-- Note: on Windows packing of 64-bit values > 2^63 currently
 -- results in packing exactly 2^63.
 -- @param format Format string, used to pack following arguments.
 -- @param ... The values to pack.
@@ -57,14 +56,15 @@ function bin.pack(format, ...)
 
 
 --- Returns values read from the binary packed data string.
--- \n\n
+--
 -- The first return value of this function is the position at which unpacking
--- stopped. This can be used as init value for subsequent calls. The following
--- results are the values according to the format string. Numerical values in
--- the format string are interpreted as repetitions like in pack, except if used
--- with A, B or H, in which cases the number tells unpack how many bytes to
--- read. Unpack stops if either the format string or the binary data string are
--- exhausted. 
+-- stopped. This can be used as the <code>init</code> value for subsequent
+-- calls. The following return values are the values according to the format
+-- string. Numerical values in the format string are interpreted as repetitions
+-- like in <code>pack()</code>, except if used with <code>A</code>,
+-- <code>B</code>, or <code>H</code>, in which cases the number tells
+-- <code>unpack</code> how many bytes to read. <code>unpack</code> stops if
+-- either the format string or the binary data string are exhausted. 
 -- @param format Format string, used to unpack values out of data string.
 -- @param data String containing packed data.
 -- @param init Optional starting position within the string.

nselib/bit.luadoc

@@ -1,21 +1,21 @@
 --- Bitwise operations on integers.
--- \n\n
+--
 -- Lua does not provide bitwise logical operations. Since they are often useful
 -- for low-level network communication, Reuben Thomas' BitLib
 -- (http://luaforge.net/projects/bitlib) for Lua has been integrated into NSE.
 -- The arguments to the bitwise operation functions should be integers.  The
 -- number of bits available for logical operations depends on the data type used
--- to represent Lua numbers--this is typically 8-byte IEEE floats (double),
+-- to represent Lua numbers. This is typically 8-byte IEEE floats (double),
 -- which give 53 bits (the size of the mantissa).
--- \n\n
+--
 -- This implies that the bitwise operations won't work (as expected) for numbers
 -- larger than 10^14. You can use them with 32-bit wide numbers without any
 -- problems. Operations involving 64-bit wide numbers, however, may not return
 -- the expected result.
--- \n\n
+--
 -- The logical operations start with "b" to avoid
--- clashing with reserved words; although xor isn't a
--- reserved word, it seemed better to use bxor for
+-- clashing with reserved words; although <code>xor</code> isn't a
+-- reserved word, it seemed better to use <code>bxor</code> for
 -- consistency.
 --
 -- @author Reuben Thomas
@@ -23,13 +23,13 @@
 
 module "bit"
 
---- Cast a to an internally-used integer type.
+--- Cast <code>a</code> to an internal integer type.
 -- @param a Number.
 function bit.cast(a)
 
---- Return the one's complement of a.
+--- Returns the one's complement of <code>a</code>.
 -- @param a Number.
--- @return The one's complement of a.
+-- @return The one's complement of <code>a</code>.
 function bit.bnot(a)
 
 --- Returns the bitwise and of all its arguments.
@@ -47,22 +47,23 @@ function bit.bor(...)
 -- @return The exclusive ored result.
 function bit.bxor(...)
 
---- Returns a left shifted by b places.
+--- Returns <code>a</code> left-shifted by <code>b</code> 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.
+--- Returns <code>a</code> right-shifted by <code>b</code> 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.
+--- Returns <code>a</code> arithmetically right-shifted by <code>b</code>
+-- places.
 -- @param a Number to perform the shift on.
 -- @param b Number of shifts.
 function bit.arshift(a, b)
 
---- Returns the integer remainder of a divided by b.
+--- Returns the integer remainder of <code>a</code> divided by <code>b</code>.
 -- @param a Dividend.
 -- @param b Divisor.
 function bit.mod(a, b)

nselib/comm.lua

@@ -77,14 +77,16 @@ local read = function(sock, opts)
 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. 
+-- specified host and returns any data received.
+--
+-- The first return value is true to signal success or false to signal
+-- failure. On success the second return value is the response from the
+-- remote host. On failure the second return value is an error message.
 -- @param host The host to connect to.
 -- @param port The port on the host.
--- @param opts The options. See module description.
--- @return bool, data
+-- @param opts The options. See the module description.
+-- @return Status (true or false).
+-- @return Data (if status is true) or error string (if status is false).
 get_banner = function(host, port, opts)
 	opts = initopts(opts)
 
@@ -105,15 +107,16 @@ 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. 
+--
+-- The first return value is true to signal success or false to signal
+-- failure. On success the second return value is the response from the
+-- remote host. On failure the second return value is an error message.
 -- @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
+-- @param opts The options. See the module description.
+-- @return Status (true or false).
+-- @return Data (if status is true) or error string (if status is false).
 exchange = function(host, port, data, opts)
 	opts = initopts(opts)
 

nselib/datafiles.lua

@@ -1,10 +1,9 @@
---- Read and parse some of Nmap's data files: nmap-protocols, nmap-rpc,
--- and nmap-services.
--- \n\n
--- The functions in this module return values appropriate for use with
--- exception handling via nmap.new_try(). On success, they return true
--- and the function result. On failure, they return false and an error
--- message.
+--- Read and parse some of Nmap's data files: <code>nmap-protocols</code>,
+-- <code>nmap-rpc</code>, and <code>nmap-services</code>.
+--
+-- The functions in this module return values appropriate for use with exception
+-- handling via <code>nmap.new_try()</code>. On success, they return true and
+-- the function result. On failure, they return false and an error message.
 -- @author Kris Katterjohn 03/2008
 -- @author jah 08/2008
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
@@ -30,11 +29,12 @@ local common_files = {
 
 
 ---
--- Read and parse nmap-protocols.
--- \n\n
--- On success, return true and a table mapping protocol numbers to
--- protocol names.
--- @return bool, table|err
+-- Read and parse <code>nmap-protocols</code>.
+--
+-- On success, return true and a table mapping protocol numbers to protocol
+-- names.
+-- @return Status (true or false).
+-- @return Table (if status is true) or error string (if status is false).
 -- @see parse_file
 parse_protocols = function()
   local status, protocols_table = parse_file("nmap-protocols")
@@ -47,10 +47,11 @@ end
 
 
 ---
--- Read and parse nmap-rpc.
--- \n\n
+-- Read and parse <code>nmap-rpc</code>.
+--
 -- On success, return true and a table mapping RPC numbers to RPC names.
--- @return bool, table|err
+-- @return Status (true or false).
+-- @return Table (if status is true) or error string (if status is false).
 -- @see parse_file
 parse_rpc = function()
   local status, rpc_table = parse_file("nmap-rpc")
@@ -63,15 +64,17 @@ end
 
 
 ---
--- Read and parse nmap-services.
--- \n\n
--- On success, return true and a table containing two subtables, indexed
--- by the keys "tcp" and "udp". The tcp table maps TCP port numbers to
--- service names, and the udp table is the same for UDP. You can pass
--- "tcp" or "udp" as an argument to parse_services to get only one of
--- the results tables.
--- @param protocol The protocol table to return ("tcp" of "udp").
--- @return bool, table|err
+-- Read and parse <code>nmap-services</code>.
+--
+-- On success, return true and a table containing two subtables, indexed by the
+-- keys "tcp" and "udp". The <code>tcp</code> subtable maps TCP port numbers to
+-- service names, and the <code>udp</code> subtable is the same for UDP. You can
+-- pass "tcp" or "udp" as an argument to <code>parse_services()</code> to get
+-- only one of the results tables.
+-- @param protocol The protocol table to return (<code>"tcp"</code> or
+-- <code>"udp"</code>).
+-- @return Status (true or false).
+-- @return Table (if status is true) or error string (if status is false).
 -- @see parse_file
 parse_services = function(protocol)
   if protocol and protocol ~= "tcp" and protocol ~= "udp" then
@@ -90,11 +93,12 @@ end
 ---
 -- Read and parse a generic data file. The other parse functions are
 -- defined in terms of this one.
--- \n\n
--- If filename is a key in common_files, use the corresponding capture
--- pattern. Otherwise the second argument must be a table of the kind
--- taken by parse_lines.
 --
+-- If filename is a key in <code>common_files</code>, use the corresponding
+-- capture pattern. Otherwise the second argument must be a table of the kind
+-- taken by <code>parse_lines</code>.
+-- @param filename Name of the file to parse.
+-- @param ... A table of capture patterns.
 -- @return A table whose structure mirrors that of the capture table,
 -- filled in with captured values.
 function parse_file(filename, ...)
@@ -150,12 +154,11 @@ end
 
 ---
 -- Generic parsing of an array of strings.
--- 
 -- @param lines An array of strings to operate on.
 -- @param data_struct A table containing capture patterns to be applied
 -- to each string in the array. A capture will be applied to each string
--- using string.match() and may also be enclosed within a table or a
--- function. If a function, it must accept a string as its parameter and
+-- using <code>string.match()</code> and may also be enclosed within a table or
+-- a function. If a function, it must accept a string as its parameter and
 -- should return one value derived from that string.
 -- @return A table whose structure mirrors that of the capture table,
 -- filled in with captured values.
@@ -205,8 +208,9 @@ end
 ---
 -- Read a file, line by line, into a table.
 -- @param file String with the name of the file to read.
--- @return      Boolean True on success, False on error
--- @return      Table (array-style) of lines read from the file or error message in case of an error.
+-- @return Status (true or false).
+-- @return Array of lines read from the file (if status is true) or error
+-- message (if status is false).
 function read_from_file( file )
 
   -- get path to file
@@ -236,8 +240,9 @@ end
 
 ---
 -- Return an array-like table of values captured from each line.
--- @param lines      table of strings containing the lines to process
--- @param v_pattern  pattern to use on the lines to produce the value for the array
+-- @param lines Table of strings containing the lines to process.
+-- @param v_pattern Pattern to use on the lines to produce the value for the
+-- array.
 get_array = function(lines, v_pattern)
   local ret = {}
   for _, line in ipairs( lines ) do
@@ -255,10 +260,12 @@ end
 
 
 ---
--- Return an associative array table of index-value pairs captured from each line.
--- @param lines      table of strings containing the lines to process
--- @param i_pattern  pattern to use on the lines to produce the key for the associative array
--- @param v_pattern  pattern to use on the lines to produce the value for the associative array
+-- Return a table of index-value pairs captured from each line.
+-- @param lines Table of strings containing the lines to process.
+-- @param i_pattern Pattern to use on the lines to produce the key for the
+-- associative array.
+-- @param v_pattern Pattern to use on the lines to produce the value for the
+-- associative array.
 get_assoc_array = function(lines, i_pattern, v_pattern)
   local ret = {}
   for _, line in ipairs(lines) do

nselib/dns.lua

@@ -1,9 +1,9 @@
-module(... or "dns", package.seeall)
-
 --- Simple DNS library supporting packet creation, encoding, decoding,
 -- and querying.
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
+module(... or "dns", package.seeall)
+
 require("ipOps")
 require("stdnse")
 
@@ -27,6 +27,10 @@ types = {
 }
 
 
+---
+-- Table of error codes.
+-- @name err
+-- @class table
 err = {
    noSuchName = 3,
    noServers = 9
@@ -40,7 +44,8 @@ err = {
 -- @param port Port to connect to.
 -- @param timeout Number of ms to wait for a response.
 -- @param cnt Number of tries.
---@return success as boolean and response if available.
+-- @return Status (true or false).
+-- @return Response (if status is true).
 local function sendPackets(data, host, port, timeout, cnt)
    local socket = nmap.new_socket()
    socket:set_timeout(timeout)
@@ -63,8 +68,8 @@ end
 
 ---
 -- Checks if a DNS response packet contains a useful answer.
---@param rPkt decoded DNS response packet.
---@return true if useful, false if not.
+-- @param rPkt Decoded DNS response packet.
+-- @return True if useful, false if not.
 local function gotAnswer(rPkt)
    -- have we even got answers?
    if #rPkt.answers > 0 then
@@ -95,8 +100,8 @@ end
 ---
 -- Tries to find the next nameserver with authority to get a result for
 -- query.
---@param rPkt decoded DNS response packet
---@return string or table of next server(s) to query or false
+-- @param rPkt Decoded DNS response packet
+-- @return String or table of next server(s) to query, or false.
 local function getAuthDns(rPkt)
    if #rPkt.auth == 0 then 
       if #rPkt.answers == 0 then
@@ -125,16 +130,18 @@ end
 
 ---
 -- Query DNS servers for a DNS record.
---@param dname wanted domain name entry
---@param options \n
--- dtype wanted DNS record type (default: A).\n
--- host DNS server to be queried (default: DNS servers known to Nmap).\n
--- port Port of DNS server to connect to (default: 53).\n
--- tries How often should query try to contact another server (for non-recursive queries).\n
--- retAll Return all answers, not just the first.\n
--- retPkt Return the packet instead of using the answer fetching mechanism.\n
--- norecurse If true, do not set the recursion (RD) flags.\n
---@return Nice answer string by an answer fetcher on success or false and an error code (see: dns.err.*)
+-- @param dname Desired domain name entry.
+-- @param options A table containing any of the following fields:
+-- * <code>dtype</code>: Desired DNS record type (default: <code>"A"</code>).
+-- * <code>host</code>: DNS server to be queried (default: DNS servers known to Nmap).
+-- * <code>port</code>: Port of DNS server to connect to (default: <code>53</code>).
+-- * <code>tries</code>: How often should <code>query</code> try to contact another server (for non-recursive queries).
+-- * <code>retAll</code>: Return all answers, not just the first.
+-- * <code>retPkt</code>: Return the packet instead of using the answer-fetching mechanism.
+-- * <code>norecurse</code> If true, do not set the recursion (RD) flag.
+-- @return Nice answer string by an answer fetcher on success or false on error.
+-- @return An error code on error.
+-- @see dns.err
 function query(dname, options)
    if not options then options = {} end
 
@@ -228,7 +235,8 @@ end
 ---
 -- Formats an IP address for reverse lookup.
 -- @param ip IP address string.
---@return "Domain" style representation of IP as subdomain of in-addr.arpa or ip6.arpa.
+-- @return "Domain"-style representation of IP as subdomain of in-addr.arpa or
+-- ip6.arpa.
 function reverse(ip)
    ip = ipOps.expand_ip(ip)
    if type(ip) ~= "string" then return nil end
@@ -268,8 +276,8 @@ local answerFetcher = {}
 ---
 -- Answer fetcher for TXT records.
 -- @param dec Decoded DNS response.
---@param retAll If true return all entries, not just the first.
---@return first entry (or all) treated as TXT.
+-- @param retAll If true, return all entries, not just the first.
+-- @return First entry (or all of them), treated as TXT.
 answerFetcher[types.TXT] = 
    function(dec, retAll)
       if not retAll then
@@ -286,8 +294,8 @@ answerFetcher[types.TXT] =
 ---
 -- Answer fetcher for A records
 -- @param dec Decoded DNS response.
---@param retAll If true return all entries, not just the first.
---@return first IP (or all) of response packet.
+-- @param retAll If true, return all entries, not just the first.
+-- @return First IP (or all of them) of response packet.
 answerFetcher[types.A] = 
    function(dec, retAll)
       local answers = {}
@@ -308,8 +316,8 @@ answerFetcher[types.A] =
 ---
 -- Answer fetcher for CNAME records.
 -- @param dec Decoded DNS response.
---@param retAll If true return all entries, not just the first.
---@return Domain entry of first answer RR (or all) in response packet.
+-- @param retAll If true, return all entries, not just the first.
+-- @return Domain entry of first answer RR (or all of them) in response packet.
 answerFetcher[types.CNAME] = 
    function(dec, retAll)
       if not retAll then
@@ -326,8 +334,8 @@ answerFetcher[types.CNAME] =
 ---
 -- Answer fetcher for MX records.
 -- @param dec Decoded DNS response.
---@param retAll If true return all entries, not just the first.
---@return Domain entry of first answer RR (or all) in response packet.
+-- @param retAll If true, return all entries, not just the first.
+-- @return Domain entry of first answer RR (or all of them) in response packet.
 answerFetcher[types.MX] = 
    function(dec, retAll)
       if not retAll then
@@ -352,8 +360,8 @@ answerFetcher[types.PTR] = answerFetcher[types.CNAME]
 ---
 -- Answer fetcher for AAAA records.
 -- @param dec Decoded DNS response.
---@param retAll If true return all entries, not just the first.
---@return first IPv6 (or all) of response packet.
+-- @param retAll If true, return all entries, not just the first.
+-- @return First IPv6 (or all of them) of response packet.
 answerFetcher[types.AAAA] = 
    function(dec, retAll)
       local answers = {}
@@ -372,12 +380,15 @@ answerFetcher[types.AAAA] =
 
 
 ---
--- Calls the answer fetcher for dtype or returns an error code on a no
--- such name error.
+-- Calls the answer fetcher for <code>dtype</code> or returns an error code in
+-- case of a "no such name" error.
 -- @param dtype DNS resource record type.
 -- @param dec Decoded DNS response.
---@param retAll If true return all entries, not just the first.
---@return answer by according answer fetcher or packet if none applicable or false and error code if flags indicate an error.
+-- @param retAll If true, return all entries, not just the first.
+-- @return Answer according to the answer fetcher for <code>dtype</code>,
+-- <code>dec</code> if no answer fetcher is known for <code>dtype</code>, or
+-- false if flags indicate an error.
+-- @return Error code on error.
 function findNiceAnswer(dtype, dec, retAll) 
    if (#dec.answers > 0) then
       if answerFetcher[dtype] then 
@@ -412,7 +423,8 @@ end
 
 ---
 -- Encodes DNS flags to a binary digit string.
---@param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, RA, RCx).
+-- @param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD,
+-- RA, RCx).
 -- @return Binary digit string representing flags.
 local function encodeFlags(flags)
    if type(flags) == "string" then return flags end
@@ -436,9 +448,11 @@ local function encodeFlags(flags)
 end
 
 ---
--- Takes a table representing a DNS packet to encode.
+-- Encode a DNS packet.
+--
 -- Caution: doesn't encode answer, authority and additional part.
---@param pkt Table representing DNS packet, initialized by newPacket().
+-- @param pkt Table representing DNS packet, initialized by
+-- <code>newPacket()</code>.
 -- @return Encoded DNS packet.
 function encode(pkt)
    if type(pkt) ~= "table" then return nil end
@@ -450,10 +464,11 @@ end
 
 
 ---
--- Decodes a domain in a DNS packet, Handles "compressed" data too.
+-- Decodes a domain in a DNS packet. Handles "compressed" data too.
 -- @param data Complete DNS packet.
 -- @param pos Starting position in packet.
---@return Position after decoding and decoded domain.
+-- @return Position after decoding. 
+-- @return Decoded domain.
 local function decStr(data, pos)
    local partlen
    local parts = {}
@@ -480,7 +495,8 @@ end
 -- @param data Complete DNS packet.
 -- @param count Value of question counter in header.
 -- @param pos Starting position in packet.
---@return Position after decoding and table of decoded questions.
+-- @return Position after decoding.
+-- @return Table of decoded questions.
 local function decodeQuestions(data, count, pos)
    local q = {}
    for i = 1, count do
@@ -498,7 +514,7 @@ end
 local decoder = {}
 
 ---
--- Decodes IP of A record, puts it in entry.ip.
+-- Decodes IP of A record, puts it in <code>entry.ip</code>.
 -- @param entry RR in packet.
 decoder[types.A] = 
    function(entry)
@@ -509,7 +525,7 @@ decoder[types.A] =
    end
 
 ---
--- Decodes IP of AAAA record, puts it in entry.ipv6.
+-- Decodes IP of AAAA record, puts it in <code>entry.ipv6</code>.
 -- @param entry RR in packet.
 decoder[types.AAAA] = 
    function(entry)
@@ -524,10 +540,11 @@ decoder[types.AAAA] =
    end
 
 ---
--- Decodes SSH fingerprint record, puts it in entry.SSHFP as defined in RFC 4255:
--- .algorithm
--- .fptype
--- .fingerprint
+-- Decodes SSH fingerprint record, puts it in <code>entry.SSHFP</code> as
+-- defined in RFC 4255.
+--
+-- <code>entry.SSHFP</code> has the fields <code>algorithm</code>,
+-- <code>fptype</code>, and <code>fingerprint</code>.
 -- @param entry RR in packet.
 decoder[types.SSHFP] =
    function(entry)
@@ -539,10 +556,14 @@ decoder[types.SSHFP] =
 
 
 ---
--- Decodes SOA record, puts it in entry.SOA.*.
---@param entry RR in packet
---@param data Complete encoded DNS packet
---@param pos Position in packet after RR
+-- Decodes SOA record, puts it in <code>entry.SOA</code>.
+--
+-- <code>entry.SOA</code> has the fields <code>mname</code>, <code>rname</code>,
+-- <code>serial</code>, <code>refresh</code>, <code>retry</code>,
+-- <code>expire</code>, and <code>minimum</code>.
+-- @param entry RR in packet.
+-- @param data Complete encoded DNS packet.
+-- @param pos Position in packet after RR.
 decoder[types.SOA] = 
    function(entry, data, pos)
 
@@ -561,8 +582,8 @@ decoder[types.SOA] =
    end
 
 ---
--- Decodes records which consist only of one domain, for example CNAME,
--- NS, PTR. Puts result in entry.domain.
+-- Decodes records that consist only of one domain, for example CNAME, NS, PTR.
+-- Puts result in <code>entry.domain</code>.
 -- @param entry RR in packet.
 -- @param data Complete encoded DNS packet.
 -- @param pos Position in packet after RR.
@@ -581,7 +602,10 @@ decoder[types.PTR] = decDomain
 decoder[types.TXT] = function () end
 
 ---
--- Decodes MX record, puts it in entry.MX.*.
+-- Decodes MX record, puts it in <code>entry.MX</code>.
+--
+-- <code>entry.MX</code> has the fields <code>pref</code> and
+-- <code>server</code>.
 -- @param entry RR in packet.
 -- @param data Complete encoded DNS packet.
 -- @param pos Position in packet after RR.
@@ -596,8 +620,7 @@ decoder[types.MX] =
 
 
 ---
--- Decodes returned resource records (answer, authority or additional
--- part).
+-- Decodes returned resource records (answer, authority, or additional part).
 -- @param data Complete encoded DNS packet.
 -- @param count Value of according counter in header.
 -- @param pos Starting position in packet.
@@ -623,7 +646,7 @@ local function decodeRR(data, count, pos)
 end
 
 ---
--- Splits string up into table of single characters.
+-- Splits a string up into a table of single characters.
 -- @param str String to be split up.
 -- @return Table of characters.
 local function str2tbl(str)
@@ -636,7 +659,7 @@ end
 
 ---
 -- Decodes DNS flags.
---@param Flags as binary digit string.
+-- @param Flags as a binary digit string.
 -- @return Table representing flags.
 local function decodeFlags(flgStr)
    flags = {}

nselib/nmap.luadoc

@@ -233,7 +233,7 @@ function socket:connect(hostid, port, protocol)
 --- Sends data on an open socket.
 -- \n\n
 -- The send method sends the data contained in the data string through an open
--- connection. On success the returns true. If the send
+-- connection. On success the function returns true. If the send
 -- operation has failed, the function returns true along with an error string.
 -- The error strings are:\n
 -- "Trying to send through a closed socket": there was no call to socket:connect