Forums

Cobra Enhancement Proposal: Documentation

General discussion about Cobra. Releases and general news will also be posted here.
Feel free to ask questions or just say "Hello".

Cobra Enhancement Proposal: Documentation

Postby todd.a » Sat Jun 20, 2009 1:10 am

Like the title? CEPs :)

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?
todd.a
Site Admin
 
Posts: 81
Location: Chicago, IL

Return to Discussion

Who is online

Users browsing this forum: No registered users and 114 guests

cron