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")