= Cobra Code Documentation = 

Cobra code can be documented internally with two constructs
    * Comments 
    * Docstrings

Comments explain or clarify code and intent.[[BR]]
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.[[br]]
The remainder of the line (upto the EOLn character) is ignored so far as 
tokenization and code generation is concerned.
{{{
#!cobra
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 '#'. [[br]]
Using multiple single comment lines this way also helps visually delineate the
descriptive block better.

{{{
#!cobra
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.
{{{
#!cobra
var _didLineContinuation as bool  # only meaningful after an EOL
}}}

 
=== !MultiLine Comments ===

Multiline comments are a block of text delimited by '''/#''' and '''#/'''.[[BR]]
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.
{{{
#!cobra
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
{{{
#!cobra
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 '''/#... #/'''
{{{
#!cobra
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. [[br]]
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 '''.no-warnings.''' (note leading and trailing '.').[[br]]
Any subsequent text after the tag is ignored.
{{{
#!cobra
# Normally this would warn with a suggestion to remove the trailing ()
callMe()    # .no-warnings.   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. [[br]]
Usually this uses a tag '''TODO:''' followed by the notation.
{{{
#!cobra
# 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 ". [[BR]]
e.g
{{{
#!cobra
"""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.[[br]]
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 [http://www.python.org/dev/peps/pep-0257/ 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 ===
{{{
#!cobra
    """ TEXT """

    """
    TEXT LINE
    SUBSEQUENT TEXT LINES ...
    """
}}}
=== Examples ===

{{{
#!cobra
"""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 ==


[wiki:LanguageTopics Back to Language Topics]