From 9d45c24835632cc834c9bef5587f7143e7038367 Mon Sep 17 00:00:00 2001 From: batrick Date: Sat, 25 Oct 2008 03:58:52 +0000 Subject: [PATCH] Updated NSEDoc C module documentation. Merged David's paragraph on the topic with mine. --- docs/scripting.xml | 49 ++++++++-------------------------------------- 1 file changed, 8 insertions(+), 41 deletions(-) diff --git a/docs/scripting.xml b/docs/scripting.xml index d3a09e6a9..c8e20ee31 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -1822,20 +1822,6 @@ license = "Same as Nmap--See http://nmap.org/book/man-legal.html" 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. - - NSE Documentation Tags @@ -1966,37 +1952,18 @@ categories = {"discovery", "external"} NSE Documentation for C Modules NSEDoc documentation can be written for libraries as well as scripts. - While Lua modules can be documented in much the same way as your - scripts, a C module requires special consideration. You must write + But while Lua modules are documented in much the same way, a C module + requires special consideration. You must write a ".luadoc" file to accompany the C module in order for it to be - documented. The file will list all functions for the C module as though + documented. These files are typically placed in the nselib directory + next to other Lua modules. The file itself will list all functions + for the C module as though they were written in Lua. You may however remove certain syntactical structures (particularly, end) when writing this - document. The following example demonstrates how documentation was - written for the C bit module. + document, as it is never compiled by Lua. Remember you may use the + @class tag to also help the parser + know what it is you are documenting, especially for tables. - - - Documentation for the C "bit" module - ---- Return the one's complement of a. --- @param a Number. --- @return The one's complement of a. -function bit.bnot(a) - ---- Returns the bitwise and of all its arguments. --- @param ... A variable number of Numbers to and. --- @return The anded result. -function bit.band(...) - - - - It is important to note that this documentation is being written for - a simple documentation parser and not Lua. The functions, - bit.bnot and bit.band, are placed there to assist in generating the - documentation. You may use the @class tag to also help the parser - know what it is you are documenting, especially for tables. -