Re: NSE Script Documentation

[Fyodor <fyodor () insecure org>]

On Tue, Jun 17, 2008 at 04:48:19AM -0600, Patrick Donnelly wrote:
> I've been working on the Documentation system this week for NSE. The
> format of the documents will be very similar to LuaDoc (see:
> http://seclists.org/nmap-dev/2008/q2/0273.html). The main difference

Thanks for the update, Patrick.  This looks quite promising.  And I'm
excited about having a good documentation system for NSE scripts and
libraries.  Here are my thoughts after looking over your proposal:

o If possibke, we should avoid repeating fields which are already in
the code.  For example, your anonftp.nse example contains these lins
in various places:
-- @require shortport
-- @category default
-- @category intrusive
categories = {"default", "intrusive"}
require "shortport"

It would be better if the system can somehow read the categories from
the variables rather than having to keep comments in sync.

In fact, maybe we can even push more of the comments into variables.
For example, is this format:

-- @author Eddie Bell <ejlbell () gmail com>

really any better than the old one:

author = "Eddie Bell <ejlbell () gmail com>"?

They are both the same length, and the latter may allow for easier use
by the scripts themselves and also allow the use of LUA literal string
features (such as [[]] for multi-line strings).

Maybe it would be easiest to continue using variables for the user
documentation fields?  IIRC, you noted ways that those can be easily
made available to Nmap, and of course they are trivially available to
the script itself.  If they are easily available to Nmap, it probably
wouldn't be too hard to make them available to a documentation
generation system.  But if there are important reasons for using
comments rather than variable assignment, that could be OK.

As for the fields, I think we should either have a short summary field
in addition to a long description, or we should require that the first
paragraph of the description be suitable as a summary for when we need
a short description of a script.

Also, we may need more of a distinction between user documentation and
developer docs.  Users need a summary, detailed description, ideally
output examples (perhaps as part of the detailed description), a list
of allowed arguments and what they do, etc.  Developers, on the other
hand, want to know about library functions, variables, etc.

Maybe it would be best to use the NSE-specific system for user
documentation, and LuaDoc for developer documentation?  If LuaDoc
already has everything we need for developer documentation, we
shouldn't reinvent the wheel.  But perhaps LuaDoc doesn't offer what
we need?

Thanks,
Fyodor

_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://SecLists.Org