Re: nsedoc observations

[jah <jah () zadkiel plus com>]

On 13/08/2008 08:19, Patrick Donnelly wrote:
> Hi Jah,
>
> Sorry for the late reply to your post:
>   
Hi Patrick - no worries.  I've added more comments and commented on your
comments about my comments:
> 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.
>   
If the description field contains a succinct description and it's
necessary to expand upon that description with usage notes then a script
would require the use of the @usage tag or similar.  Otherwise any file
comment not part of tags would override the description field. 
Therefore the short content of the description field would not be seen
in the document and its content would need to be duplicated in the file
comments.  That or place both the short description and extended
information in the file comments and use decription="" or
description=true in the script to satisfy the requirement for the
description field.

Given that it's now possible to do some formatting in the description
field (\n), I think it would be OK to prefer this for the User Summary
over file comments - as before your change.  The addition of the @usage
tag would enable documenters to keep the description field short and sweet.

> >  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.
>   
In the whois.nse I recently submitted, I did actually use the @args tag
in the end.  The layout wasn't as inflexible as I'd made out.  I just
interspersed html tags.  I've now tried replacing the html with \n, but
this doesn't currently work for @args.
>   
> > 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.
>   
Confirmed.  This is much better. \t would be useful too.  Can you make
the parser accept strings that span multiple lines which are enclosed in
[[ ]] as well as those that use end of line \

description = "foo \
bar"

and

description = [[
foo
bar
]]

>   
> > 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.
>   
Good point.  I'd much prefer not to use html in script comments - it
looks shit.
>   
> > 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.
>   
It does work - if done exactly as you've shown (i.e. the tags appear
immediately before the table declaration) .  Cheers.
>   
> > 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)?
>   
See above discussion of description.  The @usage tag would indeed be a
good place to put example commands as well as lay out different usages.
>   
> > 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.
>   
Confirmed.
> > 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?
>   
What I had in mind here is what I saw in those examples.  You could
refer to another function/script/library in context with some comments
rather than in a separate block.  Also, in addition to having a separate
block with each @see value on a separate line in the resultant document,
you could combine them onto a single line.

inline with comments:
This function is great, it's better than that other blokes (see foo).

and

separate block with all references on the same line:
See  foo, bar

and

separate block with each reference on a new line.
See
foo - for all things foo.
bar - when you want a drink.

Perhaps this is something for the back-burner, pending more interest.
>   
> > \n also didn't work for me in the @output tag.
> >     
>
> This is fixed.
>   
Confirmed.  Much better.
>   
> > Slashes appear in the document if, say, the description field uses "\"
> > to allow a multi-line string.
> >     
>
> This is fixed.
>   
Confirmed.
>   
> > 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 :)
>
>   
Right, OK.
> > 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.
>   
Nice.
> > Kris mentioned displaying required modules and I think this would be a
> > good idea too.
> >     
>
> This has been added.
>   
Yep, I think this is a good addition.
>   
> > 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).
>
>   
I'm convinced that @usage would be really useful.  That way, the
description/user summary could be kept short and sweet, but any more
detail required could be placed in @usage.  @notes wouldn't be necessary
because they could be placed in @usage.  I think that perhaps this tag
is key to providing useful information that users of a script would
benefit from knowing.

I'd like to see \t work too if possible.

Some people like to keep a track of changes which is why I suggested
@changelog.  You might be right though, these might grow large and
affect the documents adversely (although they could be pushed to the end
of the document).

There's a bit of a problem with your latest version from
svn://svn.insecure.org/nmap-exp/patrick/nsedoc and it manifests itself a
Host and Port rules appearing before much of the other content in the
documents.  See
http://www.unm.edu/~batrick/nse/docs/files/scripts/anonFTP.html
<http://www.unm.edu/%7Ebatrick/nse/docs/files/scripts/anonFTP.html>
The header for the summary of functions table has gone AWOL too.

I reckon it's about there and I'm looking forward to browsing through
the documents of other peoples scripts when I'm hunting for code to pilfer.

Regards,

jah




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