Our discussions on IRC earlier brought up questions regarding documentation. Python uses reStructuredText; however, this may be limiting since Cobra has support for static typing. We decided it would be best to borrow ideas from C#'s XML Docs, Doxygen, Pydoc, Javadoc, etc. Below is an example of what it can look like:
"""
Summary goes right at the start of the string
Further descriptions go in here. Paragraphs are separated by a blank line.
Classes methods and interfaces can probably be reflected. Could use Markdown
or Textile syntax in here.
@example
foo = Bar()
foo.show
@author
@revision
@exceptions (classes and methods only)
@since
@deprecated some deprecation information
@param (methods only)
@return (methods only)
@see FooException BarException IFooBar
"""
class Foo
pass
Any ideas for additional parameters or syntax?