Changes between Initial Version and Version 1 of CodeDoc

Timestamp:

07/08/10 13:47:49 (14 years ago)

Author:

hopscc

Comment:

--

CodeDoc

@@ +1 @@
+= 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.
+{{{
+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.
+
+{{{
+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 '''#/'''.[[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.
+{{{
+def startSource(fileName as String, source as String) as Tokenizer
+    /#
+    print '**********************************************'
+    print source
+    print '**********************************************'
+    #/
+    _fileName = fileName
+    _stream = StringReader(source)
+    .afterStart
+    return this
+}}}
+
+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. [[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 '''.nowarnings.''' (note leading and trailing '.').[[br]]
+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. [[br]]
+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 ". [[BR]]
+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.[[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)
+    * Immediately after a '''namespace''' declaration
+    * 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 ==
+
+
+[wiki:LanguageTopics Back to Language Topics]