[Bro-Dev] first try at a skeleton script

Robin Sommer robin at icir.org
Wed Sep 29 15:27:05 PDT 2010


Regarding the TODO: "Figure out a style for Sphinx-type
documentation", here are my thoughts:
    
    - As a general rule, I guess a comment block should always be
    associated with the next language element. 
    
    - The script itslef should start with a block describing the
    overall purpose of the script and perhaps potential
    caveats/things to keep in mind etc. 
    
    - Each indidivual doc section should start with a single short
    sentence summarizing the documented element, followed by further
    text going into more detail. 
    
    - Generally, all doc text is formatted in reST. However, one
    thing I always hate when writing documentation strings is adding
    all kinds of markers for things like parameters, return values,
    etc. (e.g., "@param", or ":param:"). What I've played with for
    HILTI is reducing this stuff to a minimum and extracting it from
    the structure of the text. Example:
    
         # Function for checking That. 
         #
         # This function checks That and also does This, and
         # sometimes even More.
         #
         # id: The connection for doing That. 
         #
         # Returns: True if That was successful.
         global check_that: function(id: conn_id): bool;
    
    We can parse everything out here that we need:
   
     - anything that's of the form "x: texttextext" is a parameter
     (with type information inferred from the prototype, not typed
     again). 
     
     - "Returns: texttextext" is the magic to mark the description
     of the return value. 
     
   This can be implemented via a pretty simple Sphinx plugin.
     
Thoughts?

Robin

-- 
Robin Sommer * Phone +1 (510) 722-6541 * robin at icir.org 
ICSI/LBNL    * Fax   +1 (510) 666-2956 *   www.icir.org



More information about the bro-dev mailing list