Cobra Code Documentation

Cobra code can be documented internally with two constructs

• Comments
• Docstrings

Comments explain or clarify code and intent.
Docstrings describe use of code.

Comments

Comments are used to provide some text to a person reading the code and are intended to describe implementation; i.e clarify the code used or describe intent or background to the code.

Comment lines can be placed pretty much anywhere.

There are two types of comments

• Single line
• Multiline

Grammar

# ANY COMMENT TEXT
code... # TRAILING COMMENT TEXT
    

code... /# commented out (code) within line #/ ...code... 

code...
/#
multiline block  of code or text commented out
# embedded line comment
code... # trailing comment
#/
code...

Single line comments

Single line comments are introduced with a # character.
The remainder of the line (upto the EOLn character) is ignored so far as tokenization and code generation is concerned.

numberType = if(.typeProvider, .typeProvider.numberType, DecimalType())
# parse literal to same type as numberType

A multiline block of comment text can be specified with multiple single lines starting with '#'.
Using multiple single comment lines this way also helps visually delineate the descriptive block better.

def onWHITESPACE_LINE(tok as IToken) as IToken?
    # Eat these.
    # Don't muck with perceived indentation level as
    # these kinds of lines are irrelevant.
    #print '<> onWHITESPACE_LINE'
    return nil
....
# Note: The Tokenizer class handles it's input one line at a time,
#       and retains the \n at the end of the line. This affects
#       the regex design for the tokens below.

The comment character can appear anywhere in a line so code may be described with an inline trailing comment.

var _didLineContinuation as bool  # only meaningful after an EOL

MultiLine Comments

Multiline comments are a block of text delimited by /# and #/.
Everything from the first delimiter up to and including the first occurrence of the second delimiter is ignored (including any embedded single line or trailing comments.

The most common use for this perhaps is to comment out a block of code.

def startSource(fileName as String, source as String) as Tokenizer
    /#
    print '**********************************************'
    print source
    print '**********************************************'
    #/
    _fileName = fileName
    _stream = StringReader(source)
    .afterStart
    return this

Note that if code is commented out as above ( delimiting /# and #/ on separate lines around the disabled code) the commented code can be easily re-enabled by changing the leading /# to #/#, turning the comment block into two single line comments

def startSource(fileName as String, source as String) as Tokenizer
    #/#
    print '**********************************************'
    print source
    print '**********************************************'
    #/
    ...

You can also comment (out) code within a line with inline /#... #/

x = /# -1 * #/ z * y
# same as x = z * y 

params = .paramDecls(/#skipParen=#/true)

Special Comment Strings

Cobra generates warnings for things it detects can be done in a less verbose or more snakelike manner.
Mostly this is helpful, sometimes its irritating or unnecessary.

You can suppress (all) warnings generated for a particular line with a trailing comment starting with the tag .nowarnings. (note leading and trailing '.').
Any subsequent text after the tag is ignored.

# Normally this would warn with a suggestion to remove the trailing ()
callMe()    # .nowarnings.   I like explicit () for this call

Notes

Its not uncommon to provide comments describing additional code or capability to be implemented at a later date.
Usually this uses a tag TODO: followed by the notation.

# TODO: move to CobraCore
...
# TODO: Add contract to enforce above statement

---

DocStrings

Docstrings can be placed at various specific points in cobracode and are intended as documentation to describe the use of or as a summary of the docced item.

Docstrings may be single line or multi line but in both cases are delimited start and end by triple ".
e.g

"""This is a single line docstring."""

"""
This is a multiline Docstring.

Leading summary line, blank line and descriptive text
Leading and trailing triple-" delimiter each on its own line.
"""

Docstrings are placed after the item being documented indented as if they were executable code.

Single line docstrings are intended for documenting simple really obvious cases.
Multiline are for items that require a bit more description.

For a good description of the form, format and intent of docstrings (wrt python) please see the  python PEP.

Docstrings can appear:

• At the start of a Module (File)
• ( Should be able to appear immediately after a namespace declaration but thats currently not allowed)
• Immediately after an Object declaration: class, interface, struct, mixin, enum, event
• Immediately after an extension declaration (extend)
• after a var or const declaration
• after a property definition (pro, get, set)
• after a method or cue (initializer) declaration ( def and cue)
• after a sig declaration

Grammar

    """ TEXT """

    """
    TEXT LINE
    SUBSEQUENT TEXT LINES ...
    """

Examples

"""Example module showing docstring positions"""


class AClass
    """ This is an example class containing lots of docstrings."""
    
    var _foofahCount = 0
        """Used only with green wiglets"""
        
    get hasFoofahs as bool
       """True if number of  foofahs > 0"""
       
    pro wigletIsGreen as bool
        """Triggers foofah count if true."""
    
    cue init
        """Std Initializer."""
        base.init
        
    def doNothing
        """Nothing happens in this method. comeback later"""
        pass

Notes

The cobra compiler can be run to generate html files containing code entrypoints/signatures and docstrings for each listed file.

cobra -doc standAlone.cobra

cobra -doc main.cobra -files:files.cobra

See Also

Back to Language Topics