[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