Re: nsedoc observations

["Patrick Donnelly" <batrick.donnelly () gmail com>]

Hi Jah,

Sorry for the late reply to your post:

On Mon, Jul 28, 2008 at 9:57 PM, jah <jah () zadkiel plus com> wrote:
> First off, the User Summary.  This is taken from the scripts description
> field if it exists, otherwise it seems to come from comments in the file
> not associated with a function, table etc.

This has been changed to be the other way around. The description in
the file comment is being used over the description field if it
exists. I think the best way to go is having the description field
have a succinct description of the purpose of the script and nothing
too detailed.

>  Whois.nse has got a fairly
> long description in which I've laid out some usage examples and how
> different --script-args affect the scripts behaviour.  In this instance,
> I decided not to use the available @args tag because whois only uses one
> argument, but allows it to have a variety of different values and the
> layout in @args is a little inflexible for this case.

This often happens with may scripts. The approach I've used is pick
the "best" argument value and use that.

> Formatting the description field however seems not to be possible: "\n"
> is printed as is and doesn't cause a page break and whilst whitespace is
> preserved in the final markup, it's collapsed upon rendering (which
> isn't really a bad thing).

This should be fixed now.

> I sacked the description field and instead used a file comment which
> allowed me to embed HTML tags into the script and affect the formatting
> in the resulting document.

This is probably ok, but please keep in mind that the documentation
will be made in formats other than html in the future.

> Second, tables.  Can't seem to get documentation to show for any tables
> I've documented.  This may just be me and a working example would be a
> great help.

This is a case where you should use the @name and @class tags to help
the parser out. If you do:

--- Table description.
-- @name tab
-- @class table
local tab = {...}

This should work correctly. The upcoming documentation section in the
book will make this more clear.

> The @usage tag displays for functions, but not for the script itself and
> I think that this would be great to have.

I feel that @usage wouldn't be much different from the description
itself in the file comment. Perhaps it would show an example command
that would cause the script to run (with --script-args)?

> On the HTML index page, in the side-bar list of files and on it's own
> page the script name has a zero appended to the displayed filename:
> scripts/whois.nse0.  I bet this is a windows thing, but I haven't looked
> at the issue in any detail.

This is fixed.

> It would be great to use the @see tag inline in a comment rather than a
> separate tag only and also to combine several @see values into a single
> line rather than each on a new line.  Examples here
> <http://luadoc.luaforge.net/api/files/luadoc/taglet/standard.html#file>
> and here <http://luadoc.luaforge.net/api/files/luadoc/core.html#main>.

I'm not really sure what you mean by this. Do you want the @see tag
within code separate from the documentation block?

> \n also didn't work for me in the @output tag.

This is fixed.

> Slashes appear in the document if, say, the description field uses "\"
> to allow a multi-line string.

This is fixed.

> I can't work out whether I've misunderstood their usage or whether <% %>
> and <% = %> just don't work.  I tried various things including just
> trying to get the script id to be written to the html.  This wasn't a
> serious need, I was trying to hide an html <script> tag in the lua code
> and then have it output in the doc.  I failed.

This is used in the templates for the html being produced. It isn't
for you guys :)

> Bloody w3.org validation icons seem to delay page loading by quite a
> bit, quite often.  I think Fyodor mentioned the possibility of getting
> rid of them and I'd like to +1 that!

This was removed.

> Kris mentioned displaying required modules and I think this would be a
> good idea too.

This has been added.

> There's a @release tag, but this doesn't seem to output any html - this
> actually seems to be by design so I mention it only for the sake of
> mentioning it.

It wasn't used in LuaDoc and the current system just uses the license
NSE field instead.

> Overall, nsedoc is looking great, but perhaps much of the focus is on
> documenting the functions in a script (which obviously is great) and not
> quite enough on documenting the usage of scripts for the benefit of users.

I hope it is easier now. What other suggestions do you have for improving this?

> I reckon that if \n and \t worked in the description field, in @output
> and in any other script comments this would help alot.  We have @args
> and that's good, but if @usage worked too, that would be a real
> benefit.  I'd like to see something like a @notes tag to allow for extra
> information about a script - warnings, tips etc.  Perhaps a @changelog tag?

I worry that some of this may clutter up the documents but maybe that
is just me (particularly @changelog). Some of these may be better in
the description (such as warnings).

> Anyone else had a chance to play with nsedoc yet?
>
>
> Regards,
>
> jah

Thanks again for your review Jah; it was most helpful! I'm pleased you liked it.

Cheers,

-- 
-Patrick Donnelly

"One of the lessons of history is that nothing is often a good thing
to do and always a clever thing to say."

-Will Durant

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