nasldoc

Installation

Installation is really easy, all you need to do is gem install!

    % gem install nasldoc

Usage

Using nasldoc is fairly simple; just pass it a directory or a single file that you want to generate the documentation for. nasldoc is designed to only parse .inc files which special comment markup.

    % nasldoc /opt/nessus/lib/nessus/plugins/

This will cause a directory called nasldoc/ to be created in your current directory. This directory will contain all of the generated HTML documents. After running nasldoc, open index.html inside of nasldoc/ and view the documentation.

Comment Markup

nasldoc comments are inclosed in ## blocks and use special tags to mark items. Currently, there are only 3 tags. Tags can be added in a matter of minutes to the parser.

nasldoc supports several markup tags:

@param - used to label named arguments to a function
@anonparam - used to label anonymous arguments to a function
@return - what the function returns
@deprecated - notation for functions that shouldn't be used
@nessus - minimum Nessus version supported
@category - type of category for the function
@remark - special notes or remarks

Function Description Block

The function description block is free form text from the first ## block to the first @tag in the nasldoc body. The lines are split on the # and rejoined with spaces.

Example:

    ##
    # An example addition function in NASL
    #
    # @param arg1 first number to add
    # @param arg2 second number to add
    #
    # @return the sum of arg1 and arg2
    ##
    function add(arg1, arg2)
    {
      return (arg1 + arg2);
    }

Variable types

If you'd like, you can provide variable type descriptions. The syntax is as follows:

    ##
    # An example addition function in NASL
    #
    # @param <arg1:int> first number to add
    # @param [arg2:int] second number to add
    #
    # @return the sum of arg1 and arg2
    ##
    function add(arg1, arg2)
    {
      return (arg1 + arg2);
    }

You can wrap the name:type tuple using either '[]' or '<>'.

Templates

nasldoc uses the ERB templating engine to make generating the output HTML trivial. Attached is an example of the sidebar; ruby code can be injected to help generate the layout.

Example:

    <html>
            <head>
                    <title>nasldoc</title>
                    <link rel = 'stylesheet' type= 'text/css' href='stylesheet.css'>
            </head>
            <body>
                    <img src='nessus.jpg' />
                    <br><br><br>
                    <ul>
                            <% @file_list.each_with_index do |file, i| %>
                                    <% row_class = i % 2 == 0 ? "even" : "odd" %>
                                    <% output_file = file.gsub(".", "_") %>
                                    <% output_file = File.basename(file).gsub(".", "_") %>
                                    <li class="<%= row_class %>"><a href='<%= output_file %>.html' target='content'><%= File.basename(file) %></a></li>
                            <% end %>
                    </ul>
                    <br><br><br>
                    <ul><a href='overview.html' target='content'>Home</a></ul>
            </body>
    </html>