From 2692746c42d9c46b46da81bd973cab23ec4a1f34 Mon Sep 17 00:00:00 2001 From: dmiller Date: Tue, 2 Sep 2014 18:23:06 +0000 Subject: [PATCH] NSEdoc cleanup Mostly splitting function summaries (the first paragraph of NSEdoc) from the body of the description to make the summary indexes shorter and easier to scan. Also fixed some unbalanced code tags like foo --- nselib/creds.lua | 2 +- nselib/iscsi.lua | 1 + nselib/jdwp.lua | 1 + nselib/json.lua | 1 + nselib/lfs.luadoc | 1 + nselib/msrpc.lua | 4 +- nselib/msrpctypes.lua | 133 +++++++++++++++++++++++++----------------- nselib/smb.lua | 1 + nselib/ssh1.lua | 3 +- nselib/ssh2.lua | 3 +- nselib/stdnse.lua | 5 +- nselib/tab.lua | 7 ++- nselib/unpwdb.lua | 12 ++-- 13 files changed, 106 insertions(+), 68 deletions(-) diff --git a/nselib/creds.lua b/nselib/creds.lua index 03f724ba4..e9a595639 100644 --- a/nselib/creds.lua +++ b/nselib/creds.lua @@ -277,7 +277,7 @@ Credentials = { --- Returns a credential iterator -- -- @see State - -- @param state mask containing values from the State table + -- @param state mask containing values from the State table -- @return credential iterator, returning a credential each time it's -- called. Unless filtered by the state mask all credentials -- for the host, port match are iterated over. diff --git a/nselib/iscsi.lua b/nselib/iscsi.lua index e424e195d..abb735d26 100644 --- a/nselib/iscsi.lua +++ b/nselib/iscsi.lua @@ -423,6 +423,7 @@ Packet = { } --- The communication class handles socket reads and writes +-- -- In addition it keeps track of both immediate packets and the amount of read -- packets and updates cmdsn and expstatsn accordingly. Comm = { diff --git a/nselib/jdwp.lua b/nselib/jdwp.lua index f54096984..ca0dd9d2e 100644 --- a/nselib/jdwp.lua +++ b/nselib/jdwp.lua @@ -586,6 +586,7 @@ function invokeStaticMethod(socket,id,classID,methodID,numberOfArguments,argumen end --- NewInstance Command (4) +-- -- Creates a new object of this type, invoking the specified constructor. -- The constructor method ID must be a member of the class type. -- diff --git a/nselib/json.lua b/nselib/json.lua index 108b5792d..735a27833 100644 --- a/nselib/json.lua +++ b/nselib/json.lua @@ -163,6 +163,7 @@ json = P(json); -- compile the grammar --- Parses JSON data into a Lua object. +-- -- This is the method you probably want to use if you use this library from a -- script. --@param data a json string diff --git a/nselib/lfs.luadoc b/nselib/lfs.luadoc index 2c935a634..60d436d7c 100644 --- a/nselib/lfs.luadoc +++ b/nselib/lfs.luadoc @@ -7,6 +7,7 @@ module "lfs" --- Returns a directory iterator listing the contents of the given path +-- -- Each time the iterator is called with dir_obj it returns a directory entry's -- name as a string, or nil if there are no more entries. -- diff --git a/nselib/msrpc.lua b/nselib/msrpc.lua index 5c6d21253..b4a3a2cee 100644 --- a/nselib/msrpc.lua +++ b/nselib/msrpc.lua @@ -213,7 +213,9 @@ function stop_smb(state) smb.stop(state) end ---- Bind to a MSRPC interface. Two common interfaces are SAML and SRVSVC, and can be found as +--- Bind to a MSRPC interface. +-- +-- Two common interfaces are SAML and SRVSVC, and can be found as -- constants at the top of this file. Once this function has successfully returned, any MSRPC -- call can be made (provided it doesn't depend on results from other MSRPC calls). -- diff --git a/nselib/msrpctypes.lua b/nselib/msrpctypes.lua index c8be37ea3..72a61321e 100644 --- a/nselib/msrpctypes.lua +++ b/nselib/msrpctypes.lua @@ -740,7 +740,8 @@ function marshall_int64(int64) return result end ---- Marshall an int32, which has the following format: +--- Marshall an int32 +-- -- [in] uint32 var -- -- This is simply an integer inserted into the buffer, nothing fancy. @@ -774,7 +775,8 @@ function marshall_int32_array(data) return result end ---- Marshall an int16, which has the following format: +--- Marshall an int16 +-- -- [in] uint16 var -- -- This is simply an integer inserted into the buffer, nothing fancy. @@ -797,7 +799,8 @@ function marshall_int16(int16, pad) return result end ---- Marshall an int8, which has the following format: +--- Marshall an int8 +-- -- [in] uint8 var -- -- This is simply an integer inserted into the buffer, nothing fancy. @@ -904,7 +907,9 @@ function unmarshall_int8(data, pos, pad) return pos, value end ---- Marshall a pointer to an int64. If the pointer is null, it simply marshalls the +--- Marshall a pointer to an int64. +-- +-- If the pointer is null, it simply marshalls the -- integer '0'. Otherwise, it uses a referent id followed by the integer. -- --@param int64 The value of the integer pointer @@ -919,7 +924,8 @@ function marshall_int64_ptr(int64) return result end ---- Marshall a pointer to an int32, which has the following format: +--- Marshall a pointer to an int32 +-- -- [in,out] uint32 *ptr -- -- If the pointer is null, it simply marshalls the integer '0'. Otherwise, @@ -937,7 +943,8 @@ function marshall_int32_ptr(int32) return result end ---- Marshall a pointer to an int16, which has the following format: +--- Marshall a pointer to an int16 +-- -- [in,out] uint16 *ptr -- -- If the pointer is null, it simply marshalls the integer '0'. Otherwise, @@ -956,7 +963,8 @@ function marshall_int16_ptr(int16, pad) return result end ---- Marshall a pointer to an int8, which has the following format: +--- Marshall a pointer to an int8 +-- -- [in,out] uint8 *ptr -- -- If the pointer is null, it simply marshalls the integer '0'. Otherwise, @@ -1219,8 +1227,9 @@ function unmarshall_NTTIME_ptr(data, pos) return pos, time end ----Unmarshall a SYSTEMTIME structure, converting it to a standard representation. The structure is a --- follows: +---Unmarshall a SYSTEMTIME structure, converting it to a standard representation. +-- +--The structure is as follows: -- -- -- typedef struct _SYSTEMTIME { @@ -1520,7 +1529,7 @@ end -- (dependencies: MISC) ---------------------------------- ----Unmarshall a struct with the following definition: +---Unmarshall a dom_sid struct -- -- -- typedef [public,gensize,noprint,noejs,nosize] struct { @@ -1574,7 +1583,7 @@ function unmarshall_dom_sid2_ptr(data, pos) return unmarshall_ptr(ALL, data, pos, unmarshall_dom_sid2, {}) end ----Marshall a struct with the following definition: +---Marshall a dom_sid struct -- -- -- typedef [public,gensize,noprint,noejs,nosize] struct { @@ -1860,7 +1869,7 @@ function unmarshall_lsa_SidType(data, pos) end ---Convert a lsa_SidType value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -1926,7 +1935,7 @@ function unmarshall_lsa_LookupNamesLevel(data, pos) end ---Convert a lsa_LookupNamesLevel value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -1940,7 +1949,7 @@ function lsa_LookupNamesLevel_tostr(val) return result end ----Marshall a struct with the following definition: +---Marshall a lsa_TranslatedSid2 struct -- -- -- typedef struct { @@ -1984,7 +1993,7 @@ local function marshall_lsa_TranslatedSid2(location, sid_type, rid, sid_index, u return result end ----Unmarshall a struct with the following definition: +---Unmarshall a lsa_TranslatedSid2 struct -- -- -- typedef struct { @@ -2025,7 +2034,7 @@ local function unmarshall_lsa_TranslatedSid2(location, data, pos, result) return pos, result end ----Marshall a struct with the following definition: +---Marshall a lsa_TranslatedName2 struct -- -- -- typedef struct { @@ -2104,7 +2113,7 @@ local function unmarshall_lsa_TranslatedName2(location, data, pos, result) end ----Marshall a struct with the following definition: +---Marshall a lsa_TransSidArray2 struct -- -- -- typedef struct { @@ -2134,7 +2143,7 @@ function marshall_lsa_TransSidArray2(sids) return result end ----Marshall a struct with the following definition: +---Marshall a lsa_StringLarge struct -- -- -- typedef [public] struct { @@ -2175,7 +2184,7 @@ local function unmarshall_lsa_StringLarge(location, data, pos, result) return pos, str end ----Unmarshall a struct with the following definition: +---Unmarshall a lsa_DomainInfo struct -- -- -- typedef struct { @@ -2215,7 +2224,7 @@ local function unmarshall_lsa_DomainInfo(location, data, pos, result) return pos, result end ----Unmarshall a struct with the following definition: +---Unmarshall a lsa_RefDomainList struct -- -- -- typedef struct { @@ -2260,7 +2269,7 @@ function unmarshall_lsa_RefDomainList_ptr(data, pos) return pos, result end ----Unmarshall a struct with the following definition: +---Unmarshall a lsa_TransSidArray2 struct -- -- -- typedef struct { @@ -2283,7 +2292,7 @@ function unmarshall_lsa_TransSidArray2(data, pos) return pos, result end ----Marshall a struct with the following definition: +---Marshall a lsa_QosInfo struct -- -- -- typedef struct { @@ -2311,7 +2320,7 @@ function marshall_lsa_QosInfo() return result end ----Marshall a struct with the following definition: +---Marshall a lsa_ObjectAttribute struct -- -- -- typedef struct { @@ -2343,7 +2352,7 @@ function marshall_lsa_ObjectAttribute() return result end ----Marshall a struct with the following definition: +---Marshall a lsa_SidPtr struct -- -- -- typedef struct { @@ -2367,7 +2376,7 @@ local function marshall_lsa_SidPtr(location, sid) return result end ----Marshall a struct with the following definition: +---Marshall a lsa_SidArray struct -- -- -- typedef [public] struct { @@ -2395,10 +2404,13 @@ function marshall_lsa_SidArray(sids) return result end ----Unmarshall a struct with the following definition: +---Unmarshall a lsa_SidPtr struct +-- +-- -- typedef struct { -- dom_sid2 *sid; -- } lsa_SidPtr; +-- -- --@param location The part of the pointer wanted, either HEAD (for the data itself), BODY -- (for nothing, since this isn't a pointer), or ALL (for the data). Generally, unless the @@ -2415,7 +2427,7 @@ function unmarshall_lsa_SidPtr(location, data, pos, result) return unmarshall_ptr(location, data, pos, unmarshall_dom_sid2, {}, result) end ----Unmarshall a struct with the following definition: +---Unmarshall a lsa_SidArray struct -- -- typedef [public] struct { -- [range(0,1000)] uint32 num_sids; @@ -2434,7 +2446,7 @@ function unmarshall_lsa_SidArray(data, pos) return pos, sidarray end ----Marshall a struct with the following definition: +---Marshall a lsa_TransNameArray2 struct -- -- -- typedef struct { @@ -2556,7 +2568,7 @@ function unmarshall_winreg_AccessMask(data, pos) end ---Convert a winreg_AccessMask value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -2667,7 +2679,7 @@ function unmarshall_winreg_Type_ptr(data, pos) end ---Convert a winreg_Type value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -2883,7 +2895,7 @@ function unmarshall_srvsvc_ShareType(data, pos) end ---Convert a srvsvc_ShareType value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -3107,7 +3119,9 @@ local function unmarshall_srvsvc_NetShareInfo2(location, data, pos, result) return pos, result end ----Marshall a NetShareCtr (container) type 0. It is a simple array with the following definition: +---Marshall a NetShareCtr (container) type 0. +-- +--It is a simple array with the following definition: -- -- -- typedef struct { @@ -3168,7 +3182,9 @@ function unmarshall_srvsvc_NetShareCtr0(data, pos) return pos, result end ----Marshall a NetShareCtr (container) type 1. It is a simple array with the following definition: +---Marshall a NetShareCtr (container) type 1. +-- +--It is a simple array with the following definition: -- -- -- typedef struct { @@ -3212,7 +3228,9 @@ function marshall_srvsvc_NetShareCtr1(NetShareCtr1) end ----Marshall a NetShareCtr (container) type 2. It is a simple array with the following definition: +---Marshall a NetShareCtr (container) type 2. +-- +--It is a simple array with the following definition: -- -- -- typedef struct { @@ -3441,7 +3459,9 @@ local function unmarshall_srvsvc_NetSessInfo10(location, data, pos, result) return pos, result end ----Marshall a NetSessCtr (session container) type 10. It is a simple array with the following definition: +---Marshall a NetSessCtr (session container) type 10. +-- +--It is a simple array with the following definition: -- -- -- typedef struct { @@ -3693,7 +3713,7 @@ function unmarshall_samr_ConnectAccessMask(data, pos) end ---Convert a samr_ConnectAccessMask value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -3768,7 +3788,7 @@ function unmarshall_samr_DomainAccessMask(data, pos) end ---Convert a samr_DomainAccessMask value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -3861,7 +3881,7 @@ function unmarshall_samr_AcctFlags(data, pos) end ---Convert a samr_AcctFlags value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -3926,7 +3946,7 @@ function unmarshall_samr_PasswordProperties(data, pos) end ---Convert a samr_PasswordProperties value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -3941,7 +3961,7 @@ function samr_PasswordProperties_tostr(val) end ----Unmarshall a struct with the following definition: +---Unmarshall a samr_SamEntry struct -- -- -- typedef struct { @@ -3981,7 +4001,7 @@ local function unmarshall_samr_SamEntry(location, data, pos, result) return pos, result end ----Unmarshall a struct with the following definition: +---Unmarshall a samr_SamArray struct -- -- -- typedef struct { @@ -4020,7 +4040,7 @@ function unmarshall_samr_SamArray_ptr(data, pos) return pos, result end ----Unmarshall a struct with the following definition: +---Unmarshall a samr_DispEntryGeneral struct -- -- -- typedef struct { @@ -4070,7 +4090,7 @@ local function unmarshall_samr_DispEntryGeneral(location, data, pos, result) return pos, result end ----Unmarshall a struct with the following definition: +---Unmarshall a samr_DispInfoGeneral struct -- -- -- typedef struct { @@ -4094,7 +4114,7 @@ function unmarshall_samr_DispInfoGeneral(data, pos) end ----Unmarshall a struct with the following definition: +---Unmarshall a samr_DispInfo struct -- -- -- typedef [switch_type(uint16)] union { @@ -4128,7 +4148,7 @@ function unmarshall_samr_DispInfo(data, pos) return pos, result end ----Unmarshall a struct with the following definition: +---Unmarshall a samr_DomInfo1 struct -- -- -- typedef struct { @@ -4158,7 +4178,7 @@ function unmarshall_samr_DomInfo1(data, pos) return pos, result end ----Unmarshall a struct with the following definition: +---Unmarshall a samr_DomInfo8 struct -- -- -- typedef struct { @@ -4181,7 +4201,7 @@ function unmarshall_samr_DomInfo8(data, pos) return pos, result end ----Unmarshall a struct with the following definition: +---Unmarshall a samr_DomInfo12 struct -- -- -- typedef struct { @@ -4206,7 +4226,7 @@ function unmarshall_samr_DomInfo12(data, pos) return pos, result end ----Unmarshall a union with the following definition: +---Unmarshall a samr_DomainInfo union -- -- -- typedef [switch_type(uint16)] union { @@ -4268,7 +4288,7 @@ function unmarshall_samr_DomainInfo_ptr(data, pos) return pos, result end ----Unmarshall a structure with the following definition: +---Unmarshall a samr_Ids struct -- -- -- typedef struct { @@ -4352,7 +4372,7 @@ function unmarshall_svcctl_ControlCode(data, pos) end ---Convert a svcctl_ControlCode value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -4410,7 +4430,7 @@ function unmarshall_svcctl_Type(data, pos) end --[[Convert a svcctl_Type value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -4464,7 +4484,7 @@ function unmarshall_svcctl_State(data, pos) end --[[Convert a svcctl_State value to a string that can be shown to the user. This is --- based on the _str table. +-- based on the _str table. -- --@param val The string value (returned by the unmarshall_ function) to convert. --@return A string suitable for displaying to the user, or nil if it wasn't found. @@ -4479,8 +4499,9 @@ function svcctl_State_tostr(val) end]]-- ----Unmarshall a SERVICE_STATUS struct, converting it to a table. The structure is as --- follows: +---Unmarshall a SERVICE_STATUS struct, converting it to a table. +-- +-- The structure is as follows: -- -- -- typedef struct { @@ -4616,7 +4637,9 @@ function marshall_atsvc_DaysOfWeek(flags) return result end ----Marshall a JobInfo struct. The structure is as follows: +---Marshall a JobInfo struct. +-- +--The structure is as follows: -- -- -- typedef struct { diff --git a/nselib/smb.lua b/nselib/smb.lua index d746c34b9..5039c2546 100644 --- a/nselib/smb.lua +++ b/nselib/smb.lua @@ -460,6 +460,7 @@ function start_raw(host, port) end --- This function will take a string like "a.b.c.d" and return "a", "a.b", "a.b.c", and "a.b.c.d". +-- -- This is used for discovering NetBIOS names. If a NetBIOS name is unknown, the substrings of the -- DNS name can be used in this way. -- diff --git a/nselib/ssh1.lua b/nselib/ssh1.lua index 0d4d67268..190f80b52 100644 --- a/nselib/ssh1.lua +++ b/nselib/ssh1.lua @@ -41,7 +41,8 @@ check_packet_length = function( buffer ) end --- Receives a complete SSH packet, even if fragmented --- this function is an abstraction layer to deal with +-- +-- This function is an abstraction layer to deal with -- checking the packet size to know if there is any more -- data to receive. -- diff --git a/nselib/ssh2.lua b/nselib/ssh2.lua index ca63ea890..9b410af3d 100644 --- a/nselib/ssh2.lua +++ b/nselib/ssh2.lua @@ -39,7 +39,8 @@ check_packet_length = function( buffer ) end --- Receives a complete SSH packet, even if fragmented --- this function is an abstraction layer to deal with +-- +-- This function is an abstraction layer to deal with -- checking the packet size to know if there is any more -- data to receive. -- diff --git a/nselib/stdnse.lua b/nselib/stdnse.lua index c0fef8017..8c7e80b40 100644 --- a/nselib/stdnse.lua +++ b/nselib/stdnse.lua @@ -232,6 +232,7 @@ function strsplit(pattern, text) end --- Generate a random string. +-- -- You can either provide your own charset or the function will use -- a default one which is [A-Z]. -- @param len Length of the string we want to generate. @@ -549,7 +550,9 @@ function format_timestamp(t, offset) end --- Format the difference between times t2 and t1 --- into a string in one of the forms (signs may vary): +-- into a string +-- +-- String is in one of the forms (signs may vary): -- * 0s -- * -4s -- * +2m38s diff --git a/nselib/tab.lua b/nselib/tab.lua index a008e1013..abb59a24d 100644 --- a/nselib/tab.lua +++ b/nselib/tab.lua @@ -71,9 +71,10 @@ function addrow(t, ...) nextrow(t) 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. -- @param t The table. function nextrow(t) assert(t) diff --git a/nselib/unpwdb.lua b/nselib/unpwdb.lua index 0e3e409bd..6159c4f4b 100644 --- a/nselib/unpwdb.lua +++ b/nselib/unpwdb.lua @@ -134,8 +134,9 @@ table_iterator = function(table) end end ---- Returns the suggested number of seconds to attempt a brute force attack, --- based on the unpwdb.timelimit script argument, Nmap's timing +--- Returns the suggested number of seconds to attempt a brute force attack +-- +-- Based on the unpwdb.timelimit script argument, Nmap's timing -- values (-T4 etc.) and whether or not a user-defined list is -- used. -- @@ -209,9 +210,10 @@ local passwords_raw = function() return true, table_iterator(passtable) end ---- Wraps time and count limits around an iterator. When either limit expires, --- starts returning nil. Calling the iterator with an argument of --- "reset" resets the count. +--- Wraps time and count limits around an iterator. +-- +-- When either limit expires, starts returning nil. Calling the +-- iterator with an argument of "reset" resets the count. -- @param time_limit Time limit in seconds. Use 0 or nil for no limit. -- @param count_limit Count limit in seconds. Use 0 or nil for no limit. -- @return boolean Status.