README-eric5-doc.txt

changeset 15
f6ccc31d6e72
child 59
6f891dcc93d9
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README-eric5-doc.txt	Sat Jan 02 17:09:08 2010 +0000
@@ -0,0 +1,189 @@
+README for the eric4-doc documentation generator
+
+    eric4-doc is the documentation generator of the eric4 IDE. Python source
+    code documentation may be included as ordinary Python doc-strings or as 
+    documentation comments. For Quixote Template files (PTL) only documentation 
+    comments are available due to the inner workings of Quixote. Documentation 
+    comments start with the string ###, followed by the contents and ended by 
+    ###. Every line of the documentation comments contents must start with a # 
+    (see example below).
+    
+    For Ruby files, the documentation string must be started with "=begin edoc"
+    and must be ended with "=end". The documentation string for classes, modules
+    and functions/methods must follow their defininition.
+    
+    Documentation for packages (i.e. directories) must be in a file called 
+    __init__.py or __init__.rb. If a package directory doesn't contain a file
+    like these, documentation for files in this directory is suppressed.
+    
+    The documentation consist of two parts. The first part is the description of 
+    the module, class, function or method. The second part, separated from the 
+    first by a blank line, consists of one or more tags. These are described below.
+    
+    eric4-doc produces HTML files from the documentation found within the source 
+    files scaned. It understands the following commandline parameters next to others.
+    
+    -o directory
+      Generate files in the named directory.
+    
+    -R, -r
+      Perform a recursive search for Python files.
+    
+    -x directory
+      Specify a directory basename to be excluded. This option may be repeated
+      multiple times.
+    
+    -i
+      Don't generate index files.
+    
+    Just type "eric4-doc" to get some usage information.
+    
+    Description
+    -----------
+    The descriptions are HTML fragments and may contain most standard HTML. The
+    description text is included in the output wrapped in P tags, but unchanged 
+    otherwise. Paragraphs have to be separated by a blank line. In order to
+    generate a blank line in the output enter a line that contains a single dot
+    (.). Reserved HTML entities (<, > and &) and the at-sign (@) at the beginning 
+    of a line, if that line doesn't contain a tag (see below), must be properly 
+    escaped. "<" should be written as "&lt;", ">" as "&gt;", "&" as "&amp;" and
+    "@" should be escaped as "@@".
+    
+    The documentation string or documentation comment may contain block tags
+    and inline tags. Inline tags are denoted by curly braces and can be placed
+    anywhere in the main description or in the description part of block tags.
+    Block tags can only be placed in the tag section that follows the main
+    description. Block tags are indicated by an at-sign (@) at the beginning of
+    the line. The text before the first tag is the description of a module, class,
+    method or function.
+    
+    Python Docstring:
+        """
+        This is sentence one, which gets included as a short description.
+        All additional sentences are included into the full description.
+        
+        @param param1 first parameter
+        @exception ValueError list entry wasn't found
+        @return flag indicating success
+        """
+        
+    Python/Quixote Documentation comment:
+        ###
+        # This is line one, which gets included as a short description.
+        # All additional lines are included into the full description.
+        #
+        # @param param1 first parameter
+        # @exception ValueError list entry wasn't found
+        # @return flag indicating success
+        ###
+        
+    Ruby Docstring:
+        =begin edoc
+        This is line one, which gets included as a short description.
+        All additional lines are included into the full description.
+        
+        @param param1 first parameter
+        @exception ValueError list entry wasn't found
+        @return flag indicating success
+        =end
+
+    Block Tags
+    ----------
+    The block tags recogized by eric4-doc are:
+
+    @@
+        This isn't really a tag. This is used to escape an at sign at the beginning
+        of a line. Everything after the first @ is copied verbatim to the output.
+
+    @author author
+        This tag is used to name the author of the code. For example:
+        @author Detlev Offenbach <detlev@die-offenbachs.de>
+
+    @deprecated description
+        This tag is used to mark a function or method as deprecated. It is always 
+        followed by one or more lines of descriptive text.
+
+    @event eventname description
+        This tag is used to describe the events (PyQt) a class may emit. It is 
+        always followed by the event name and one or more lines of descriptive 
+        text. For example:
+        
+        @event closeEvent Emitted when an editor window is closed.
+    
+    @exception exception description
+        These tags are used to describe the exceptions a function or method may 
+        raise. It is always followed by the exception name and one or more lines 
+        of descriptive text. For example:
+        
+        @exception ValueError The searched value is not contained in the list.
+    
+    @keyparam name description
+        This tag is like the @param tag, but should be used for parameters, that 
+        should always be given as keyword parameters. It is always followed by 
+        the argument name and one or more lines of descriptive text. For example:
+        
+        @keyparam extension Optional extension of the source file.
+    
+    @param name description
+        This tag is used to describe a function or method argument. It is always 
+        followed by the argument name and one or more lines of descriptive text.
+        For example:
+        
+        @param filename Name of the source file.
+    
+    @raise exception description
+        This tag is an alias for the @exception tag.
+
+    @return description
+        This tag is used to describe a functions or methods return value. It can 
+        include one or more lines of descriptive text. For example:
+        
+        @return list of description strings
+    
+    @see reference
+        This tag is used to include a reference in the documentation. It comes in
+        three different forms.
+
+        @see "string"
+            Adds a text entry of string. No link is generated. eric4-doc distinguishes
+            this form from the others by looking for a double-quote (") as the first
+            character. For example:
+
+            @see "eric4-doc readme file"
+
+        @see <a href="URL#value">label</a>
+            Adds a link as defined by URL#value. eric4-doc distinguishes this form from
+            the others by looking for a less-than symbol (<) as the first character.
+            For example:
+
+            @see <a href="eric4.eric4-doc.html>eric4-doc documentation generator</a>
+
+        @see package.module#member label
+            Adds a link to "member" in "module" in "package". package can be a package
+            path, where the package names are separated by a dot character (.). The
+            "package.module#member" part must not be split over several lines and
+            must name a valid target within the documentation directory. For example:
+
+            @see eric4.eric4-doc#main eric4-doc main() function
+            @see eric4.DocumentationTools.ModuleDocumentor#ModuleDocument.__genModuleSection
+                ModuleDocument.__genModuleSection
+
+    @signal signalname description
+        This tag is used to describe the signals (PyQt) a class may emit. It is 
+        always followed by the signal name and one or more lines of descriptive 
+        text. For example:
+        
+        @signal lastEditorClosed Emitted after the last editor window was 
+            closed.
+    
+    @throws exception description
+        This tag is an alias for the @exception tag.
+
+    Inline Tags
+    -----------
+    The inline tags recogized by eric4-doc are:
+
+    {@link package.module#member label}
+        Inserts an in-line link with visible text label that points to the documentation
+        given in the reference. This tag works he same way as the @see block tag of this
+        form.

eric ide

mercurial