diff --git a/docs/scripting.xml b/docs/scripting.xml index 7df3e949c..0bdbd0b82 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -1659,104 +1659,184 @@ local localip, localport = client_service:get_info() Script Documentation Writing - Nmap Scripting Engine (NSE)Documentation Writing + Nmap Scripting Engine (NSE)documentation in + NSEDocNmap Scripting Engine, documentation in - Scripts are used by more than just the author, so it is useful to have - documentation for users and other developers to browse through - when looking - for scripts to run against a host. For this reason, - NSE provides a system - that will produce complete documentation for its library - of scripts. - - - The documentation - is put in comments around your code. The trigger for a - documentation comment is ---. Only the first - line in the block of comments should use the prefix trigger; - subsequent lines should use Lua's standard single line comment - prefix: --. - - - The first paragraphs are used as a description for the code - following the comments. The first sentence of this description - is used as a summary (for a brief description in the index). - Optional tags can follow the description using the format - @tag .... See - for more information. - - - The first comment block not followed by a function or table - definition will - be used for a file's comment. This comment will serve for documenting - general information concerning the script. The description of this - tag should explain the script's purpose and what it does. - The file comment should also - contain an output tag showing expected output for the script and - an args tag for any arguments the script expects. + Scripts are used by more than just their author, so scripts must + have documentation. NSE modules need documentation so developers can + use them in their scripts. NSE's documentation system, described in + this section, aims to meet both these needs. While reading this + section, you may want to browse NSE's online documentation, which is + generated using this documentation. It is at + . - - Documentation Format - - Documentation for a script consists of three basic parts: a file - comment, a function or table comment, and standard NSE script fields - (e.g. description or author). - A file comment is the first documentation comment in a script and - is not followed by a function definition or table. The following - example demonstrates a file comment: - ---- Checks if an FTP server allows anonymous logins. + + NSE uses a customized version of the + LuaDoc + documentation system called NSEDoc. The documentation for scripts + and modules is contained in their source code, in the form of + comments with a special form. + + is an NSEDoc comment taken from the + stdnse.print_debug function. + + + + + + An NSEDoc comment for a function + +--- Prints a formatted debug message if the current verbosity level is greater +-- than or equal to a given level. +-- +-- This is a convenience wrapper around +-- <code>nmap.print_debug_unformatted()</code>. The first optional numeric +-- argument, <code>verbosity</code>, is used as the verbosity level necessary +-- to print the message (it defaults to 1 if omitted). All remaining arguments +-- are processed with Lua's <code>string.format()</code> function. +-- @param level Optional verbosity level. +-- @param fmt Format string. +-- @param ... Arguments to format. + + + + + Documentation comments start with three dashes: + ---. The body of the comment is the description + of the following code. The first paragraph of the description should + be a brief summary, with the following paragraphs giving more + detail. Special tags starting with @ mark off + other parts of the documentation. In the above example you see + @param, which is used to describe each parameter + of the function. A complete list of the documentation tags is found + in . + + + + Text enclosed in the HTML-like <code> and + </code> tags will be rendered in a + monospace font. This should be used for variable and function names, + as well as multi-line code examples. When a sequence of lines start + with the characters * , they will + be rendered as a bulleted list. + + + + It is good practice to document every public function and table in a + script or module. Additionally every script and module should have + its own file-level documentation. A documentation comment at the + beginning of a file (that is not followed by a function or table + definition) applies to the entire file. File-level documentation can + and should be several paragraphs long, with all the high-level + information useful to a developer using a module or a user running a + script. + + shows documenatation for the comm module (with a + few paragraphs removed to save space). Recall that module- and + script-level comments are at the very beginning of a file. + + + + An NSEDoc comment for a module + +--- Common communication functions for network discovery tasks like +-- banner grabbing and data exchange. +-- +-- These functions may be passed a table of options, but it's not +-- required. The keys for the options table are "bytes", "lines", +-- "proto", and "timeout". "bytes" sets a minimum number of bytes to +-- read. "lines" does the same for lines. "proto" sets the protocol to +-- communicate with, defaulting to "tcp" if not provided. "timeout" sets +-- the socket timeout (see the socket function +-- <code>set_timeout()</code> for details). +-- @author Kris Katterjohn 04/2008 +-- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html + + + + + There are some special considerations when documenting scripts as + opposed to functions and modules. Some information that might be put + in an @-tag in a comment should go in one of the + special script variables instead. (Script variables are described in + .) Specifically, the script's + description should be in the description variable + rather than in a documentation comment, and the information that + would go in @author and + @copyright should go in the variables + author and license instead. + NSEDoc knows about these variables and will use them in preference + to fields in the comments. Scripts should also have an + @output tag showing sample output. + + shows proper form for script-level documentation, using a + combination of documentation comments and NSE variables. + + + + + An NSEDoc comment for a script + +id = "AS Numbers" +description = [[ +Maps IP addresses to autonomous system (AS) numbers. + +The script works by sending DNS TXT queries to a DNS server which in +turn queries a third-party service provided by Team Cymru +(team-cymru.org) using an in-addr.arpa style zone set-up especially for +use by Nmap. +]] + +--- +-- @usage +-- nmap --script ASN.nse [--script-args dns=<dns server>] <target> +-- @args dns The address of a recursive nameserver to use (optional). -- @output --- |_ Anonymous FTP: Anonymous login allowed - - The standard NSE fields are used to gather other information about a - script such as the author or its categories: - -author = "Eddie Bell" +-- Host script results: +-- | AS Numbers: +-- | BGP: 64.13.128.0/21 | Country: US +-- | Origin AS: 10565 SVCOLO-AS - Silicon Valley Colocation, Inc. +-- | Peer AS: 3561 6461 +-- | BGP: 64.13.128.0/18 | Country: US +-- | Origin AS: 10565 SVCOLO-AS - Silicon Valley Colocation, Inc. +-- |_ Peer AS: 174 2914 6461 + +author = "jah, Michael" license = "Same as Nmap--See http://nmap.org/book/man-legal.html" -id = "Anonymous FTP" -categories = {"default", "intrusive"} - - These fields will be present in the final documentation. The - description field is used for the User Summary if a description in - the file comment or the file comment itself is absent. It is best - if the description field is succinct while the file comment has an - extensive description of the script. - - - Finally, a documentation comment may precede a function or - table definition: - ---- Convert two bytes into a 16bit number. ---@param data String of data. ---@param idx Index in the string (first of two consecutive bytes). ---@return 16 bit number represented by the two bytes. -function bto16(data, idx) - local b1 = string.byte(data, idx) - local b2 = string.byte(data, idx+1) - -- (b2 & 0xff) | ((b1 & 0xff) << 8) - return bit.bor(bit.band(b2, 255), bit.lshift(bit.band(b1, 255), 8)) -end - - You may also choose to document the action, portrule, or hostrule - functions. They are separated from other functions in the final - documentation for improved visibility. - - +categories = {"discovery", "external"} + + + + + What about documentation for compiled modules, which have no Lua + source code? It is kept in special files with the extension + .luadoc in the nselib + directory with the normal Lua modules. For example, the compiled + pcre module is documented in a file + pcre.luadoc. These dummy modules + look just like like normal modules, with a module name, + documentation comments, and declarations of files and tables, but + they have no code to define them. There are several examples of this + method of documentation in the Nmap source distribution. + + - Tags + NSE Documentation Tags - The following tags can be used: + This is a list of tags understood by NSEDoc and their purpose. - Describe function parameters. The first alphanumeric word - must be the parameter being documented. + Describes a function parameter. The first word following + @param is the name of the parameter + being described. The tag should appear once for each + parameter of the function. @@ -1764,7 +1844,7 @@ end - Refer to other functions or tables. + Adds a cross-reference to another function or table. @@ -1772,7 +1852,9 @@ end - Describe the return values of a function. + Describes a return value of a function. + @return may be used multiple times for + multiple return values. @@ -1780,16 +1862,10 @@ end - Describe the usage of a function or variable. - - - - - - - - The description of a function or table; this is normally - inferred from the beginning of the documentation comment. + Gives an example of the usage of a function or script. In + the case of a function, the example is Lua code; for a + script it is an Nmap command line. + @usage may be given more than once. @@ -1797,9 +1873,9 @@ end - The name of the function or table definition. This should - be used only if the documentation system cannot infer the - name by code analysis. + Defines a name for the function or table being documented. + This tag is normally not necessary, as NSEDoc infers the + name through code analysis. @@ -1807,9 +1883,11 @@ end - Like @name, if the name of the variable - is not being correctly inferred through code analysis, you - may specify the class (function or table) explicitly. + Defines the class of the thing being + modified: function, + table, or module. + Like @name, this is normally inferred + automatically. @@ -1817,15 +1895,8 @@ end - Describe a table field definition. - - - - - - - - Free format string to describe the module or file release. + In the documentation of a table, describes the value of a + named field. @@ -1833,20 +1904,12 @@ end - This tag is special to the file comment. It allows you specify - arguments to the script (via --script-args) that your script - uses. The first alphanumeric word (literally matching in Lua - ([%w%p]+)) is used as the name for - the argument, the rest its description. - - - - - - - - This allows you to specify the summary explicitly different - from the first sentence of the description. + Describes a script argument, as used with the + option (see + ). The first word after + @args is the name of the argument, and + everything following that is the description. This tag is + special to script-level comments. @@ -1854,13 +1917,37 @@ end - This tag is special to thie file comment. It allows you to - show typical output of a script. You may use "\n" to - force a line break where you please. + Shows sample output of a script. This tag is special to + script-level comments. + + + + + + + + Lists an author of a module. It may be given more than + once. Don't use this tag in script documentation; use the + author variable instead. + + + + + + + + Describes the copyright of a module. Don't use this tag in + script documentation; use the license + variable instead. + +