Re: Showing local functions in NSEDoc

[Kris Katterjohn <katterjohn () gmail com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 10/15/2010 09:52 AM, Ron wrote:
> On Thu, 14 Oct 2010 23:12:59 -0400 Patrick Donnelly <batrick () batbytes com> wrote:
> > The local functions might be later exposed in another way so I don't
> > think we should stop NSEDoc from handling local functions. Instead,
> > author's should not turn on NSEDoc (---) when documenting private
> > functions. (They can still use the NSEDoc syntax for consistency I
> > guess.)
>
> My thought is this. I want to write a script that uses the DNS library. So I open up the NSEDoc for DNS and get this:
> http://nmap.org/nsedoc/lib/dns.html
>
> There are over 30 functions defined there, most of which are completely irrelevant to somebody who just wants to use 
> the DNS library. Same deal with dhcp:
> http://nmap.org/nsedoc/lib/dhcp.html
>
> There are over 12 functions defined there, but only one that people actually can (and should) use.
>
> If NSEDoc is supposed to help people write scripts, including local functions in it is, in my opinion, making things 
> more difficult.

I agree here, but if simply not using "---" prevents the NSEDoc from
being generated (which was my understanding and also Patrick mentions
this above) then I think that's a good enough solution (since this is
NSEDoc syntax).

I don't think NSEDoc system should behave this way: "the author writes
in NSEDoc format, but I should ignore what appears to be the author's
wishes if the function is defined as local" because viewed this way it
seems like the author is conflicted.

Of course, if NSEDoc blatantly ignored the author or if it was always
generating docs for local functions without the NSEDoc "---" syntax then
I would be all for changing NSEDoc (but this isn't the case AFAIK).

> Ron

Cheers,
Kris Katterjohn

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQIcBAEBAgAGBQJMuIuiAAoJEEQxgFs5kUfufmgP/iRyXUrtrEpIdFSDwPVwIj1b
rNJAf7S6tdIPZgn9oWUw2Yq9qJ6DEFHLQrezbabWBDoXL9VWTrl4qGAnFcB+5hcT
ACTU+qEPaLybN7jy/fNnmzKgDB0kbq1Gm0jELoJriFeMXPYP2Wb0n56BudDmuaz5
J4Mtr5r7Gzcyy4Hnwoz1yPFanc0b1NgLzy8FeeyRM7lKf4X5oSC/6QZP7FcNxxIL
z2PobnE2/FYyLDK+HHGha/8mKGEMhvKTb8kQobPfi3cEizpSoWG2nh/0mmugLGai
CAaQ2WFAKOZF3hLrikauA7rABdi/3DiiN2sTMqufrDsdKC2h3b4ShO6u01QFR4Mt
dms9BJOMe8SWTw9mcgxDBAASKhqmmkCUW5yV/UcydRE/H09EVLOK/TR1XX12Rw+a
MpuGvZ+6ElSHUp4sM5OX61yCSWJe8IsUjsFG2d5Juqb5TdEl8OrrXI4iRbVtPoi1
OeNk3y+ROS36ykAtJQI9kHAHz2D0OqG1Gzde3AQCrhHb4V1WLmuxCsA3aB8o/eDi
pu493SoH8flXvQQqB5tHrhpJk4nzbhqm1MH2AowRMN/L35xJ4TdYsqfBdGy+CPqo
Gxo0/XgJwZ2qleGESJVlpIyJclnlwZL5B7zQPh66R6xm69uMcOn8/UOC1q6AFkwH
Z3l7nvz1lAMScylJZAZn
=q0dU
-----END PGP SIGNATURE-----
_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://seclists.org/nmap-dev/