Added tags to describe the type of parameters (@type, @ptype) and return values (@rtype).

Sat, 30 May 2015 12:38:30 +0200

author
Detlev Offenbach <detlev@die-offenbachs.de>
date
Sat, 30 May 2015 12:38:30 +0200
changeset 4267
94496d77156b
parent 4266
17c215c416ba
child 4269
5ba44a2de31a

Added tags to describe the type of parameters (@type, @ptype) and return values (@rtype).

APIs/Python3/eric6.api file | annotate | diff | comparison | revisions
Documentation/Help/source.qch file | annotate | diff | comparison | revisions
Documentation/Source/eric6.DocumentationTools.ModuleDocumentor.html file | annotate | diff | comparison | revisions
Documentation/Source/eric6.DocumentationTools.TemplatesListsStyle.html file | annotate | diff | comparison | revisions
Documentation/Source/eric6.DocumentationTools.TemplatesListsStyleCSS.html file | annotate | diff | comparison | revisions
DocumentationTools/ModuleDocumentor.py file | annotate | diff | comparison | revisions
DocumentationTools/TemplatesListsStyle.py file | annotate | diff | comparison | revisions
DocumentationTools/TemplatesListsStyleCSS.py file | annotate | diff | comparison | revisions
README-eric6-doc.rst file | annotate | diff | comparison | revisions
changelog file | annotate | diff | comparison | revisions
--- a/APIs/Python3/eric6.api	Mon May 25 16:28:18 2015 +0200
+++ b/APIs/Python3/eric6.api	Sat May 30 12:38:30 2015 +0200
@@ -1108,11 +1108,13 @@
 eric6.DocumentationTools.TemplatesListsStyle.methodTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.moduleTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.paragraphTemplate?7
+eric6.DocumentationTools.TemplatesListsStyle.parameterTypesListEntryTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.parametersListEntryTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.parametersListTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.rbFileTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.rbModuleTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.rbModulesClassTemplate?7
+eric6.DocumentationTools.TemplatesListsStyle.returnTypesTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.returnsTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.seeLinkTemplate?7
 eric6.DocumentationTools.TemplatesListsStyle.seeListEntryTemplate?7
@@ -1143,11 +1145,13 @@
 eric6.DocumentationTools.TemplatesListsStyleCSS.methodTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.moduleTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.paragraphTemplate?7
+eric6.DocumentationTools.TemplatesListsStyleCSS.parameterTypesListEntryTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.parametersListEntryTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.parametersListTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.rbFileTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.rbModuleTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.rbModulesClassTemplate?7
+eric6.DocumentationTools.TemplatesListsStyleCSS.returnTypesTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.returnsTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.seeLinkTemplate?7
 eric6.DocumentationTools.TemplatesListsStyleCSS.seeListEntryTemplate?7
Binary file Documentation/Help/source.qch has changed
--- a/Documentation/Source/eric6.DocumentationTools.ModuleDocumentor.html	Mon May 25 16:28:18 2015 +0200
+++ b/Documentation/Source/eric6.DocumentationTools.ModuleDocumentor.html	Sat May 30 12:38:30 2015 +0200
@@ -407,22 +407,19 @@
 </dd>
 </dl><a NAME="ModuleDocument.__genParamDescriptionListSection" ID="ModuleDocument.__genParamDescriptionListSection"></a>
 <h4>ModuleDocument.__genParamDescriptionListSection</h4>
-<b>__genParamDescriptionListSection</b>(<i>_list, template</i>)
+<b>__genParamDescriptionListSection</b>(<i>_list</i>)
 <p>
         Private method to generate the list section of a description.
 </p><dl>
 <dt><i>_list</i></dt>
 <dd>
-List containing the info for the
-            list section.
-</dd><dt><i>template</i></dt>
-<dd>
-The template to be used for the list. (string)
+list containing the info for the parameter description
+            list section (list of lists with three elements)
 </dd>
 </dl><dl>
 <dt>Returns:</dt>
 <dd>
-The list section. (string)
+formatted list section (string)
 </dd>
 </dl><a NAME="ModuleDocument.__genRbModulesClassesListSection" ID="ModuleDocument.__genRbModulesClassesListSection"></a>
 <h4>ModuleDocument.__genRbModulesClassesListSection</h4>
--- a/Documentation/Source/eric6.DocumentationTools.TemplatesListsStyle.html	Mon May 25 16:28:18 2015 +0200
+++ b/Documentation/Source/eric6.DocumentationTools.TemplatesListsStyle.html	Sat May 30 12:38:30 2015 +0200
@@ -25,7 +25,7 @@
 </p>
 <h3>Global Attributes</h3>
 <table>
-<tr><td>authorInfoTemplate</td></tr><tr><td>classTemplate</td></tr><tr><td>constructorTemplate</td></tr><tr><td>deprecatedTemplate</td></tr><tr><td>eventsListEntryTemplate</td></tr><tr><td>eventsListTemplate</td></tr><tr><td>exceptionsListEntryTemplate</td></tr><tr><td>exceptionsListTemplate</td></tr><tr><td>footerTemplate</td></tr><tr><td>functionTemplate</td></tr><tr><td>headerTemplate</td></tr><tr><td>indexBodyTemplate</td></tr><tr><td>indexListEntryTemplate</td></tr><tr><td>indexListModulesTemplate</td></tr><tr><td>indexListPackagesTemplate</td></tr><tr><td>listEntryDeprecatedTemplate</td></tr><tr><td>listEntryNoneTemplate</td></tr><tr><td>listEntrySimpleTemplate</td></tr><tr><td>listEntryTemplate</td></tr><tr><td>listTemplate</td></tr><tr><td>methodTemplate</td></tr><tr><td>moduleTemplate</td></tr><tr><td>paragraphTemplate</td></tr><tr><td>parametersListEntryTemplate</td></tr><tr><td>parametersListTemplate</td></tr><tr><td>rbFileTemplate</td></tr><tr><td>rbModuleTemplate</td></tr><tr><td>rbModulesClassTemplate</td></tr><tr><td>returnsTemplate</td></tr><tr><td>seeLinkTemplate</td></tr><tr><td>seeListEntryTemplate</td></tr><tr><td>seeListTemplate</td></tr><tr><td>signalsListEntryTemplate</td></tr><tr><td>signalsListTemplate</td></tr><tr><td>sinceInfoTemplate</td></tr>
+<tr><td>authorInfoTemplate</td></tr><tr><td>classTemplate</td></tr><tr><td>constructorTemplate</td></tr><tr><td>deprecatedTemplate</td></tr><tr><td>eventsListEntryTemplate</td></tr><tr><td>eventsListTemplate</td></tr><tr><td>exceptionsListEntryTemplate</td></tr><tr><td>exceptionsListTemplate</td></tr><tr><td>footerTemplate</td></tr><tr><td>functionTemplate</td></tr><tr><td>headerTemplate</td></tr><tr><td>indexBodyTemplate</td></tr><tr><td>indexListEntryTemplate</td></tr><tr><td>indexListModulesTemplate</td></tr><tr><td>indexListPackagesTemplate</td></tr><tr><td>listEntryDeprecatedTemplate</td></tr><tr><td>listEntryNoneTemplate</td></tr><tr><td>listEntrySimpleTemplate</td></tr><tr><td>listEntryTemplate</td></tr><tr><td>listTemplate</td></tr><tr><td>methodTemplate</td></tr><tr><td>moduleTemplate</td></tr><tr><td>paragraphTemplate</td></tr><tr><td>parameterTypesListEntryTemplate</td></tr><tr><td>parametersListEntryTemplate</td></tr><tr><td>parametersListTemplate</td></tr><tr><td>rbFileTemplate</td></tr><tr><td>rbModuleTemplate</td></tr><tr><td>rbModulesClassTemplate</td></tr><tr><td>returnTypesTemplate</td></tr><tr><td>returnsTemplate</td></tr><tr><td>seeLinkTemplate</td></tr><tr><td>seeListEntryTemplate</td></tr><tr><td>seeListTemplate</td></tr><tr><td>signalsListEntryTemplate</td></tr><tr><td>signalsListTemplate</td></tr><tr><td>sinceInfoTemplate</td></tr>
 </table>
 <h3>Classes</h3>
 <table>
--- a/Documentation/Source/eric6.DocumentationTools.TemplatesListsStyleCSS.html	Mon May 25 16:28:18 2015 +0200
+++ b/Documentation/Source/eric6.DocumentationTools.TemplatesListsStyleCSS.html	Sat May 30 12:38:30 2015 +0200
@@ -25,7 +25,7 @@
 </p>
 <h3>Global Attributes</h3>
 <table>
-<tr><td>authorInfoTemplate</td></tr><tr><td>classTemplate</td></tr><tr><td>constructorTemplate</td></tr><tr><td>deprecatedTemplate</td></tr><tr><td>eventsListEntryTemplate</td></tr><tr><td>eventsListTemplate</td></tr><tr><td>exceptionsListEntryTemplate</td></tr><tr><td>exceptionsListTemplate</td></tr><tr><td>footerTemplate</td></tr><tr><td>functionTemplate</td></tr><tr><td>headerTemplate</td></tr><tr><td>indexBodyTemplate</td></tr><tr><td>indexListEntryTemplate</td></tr><tr><td>indexListModulesTemplate</td></tr><tr><td>indexListPackagesTemplate</td></tr><tr><td>listEntryDeprecatedTemplate</td></tr><tr><td>listEntryNoneTemplate</td></tr><tr><td>listEntrySimpleTemplate</td></tr><tr><td>listEntryTemplate</td></tr><tr><td>listTemplate</td></tr><tr><td>methodTemplate</td></tr><tr><td>moduleTemplate</td></tr><tr><td>paragraphTemplate</td></tr><tr><td>parametersListEntryTemplate</td></tr><tr><td>parametersListTemplate</td></tr><tr><td>rbFileTemplate</td></tr><tr><td>rbModuleTemplate</td></tr><tr><td>rbModulesClassTemplate</td></tr><tr><td>returnsTemplate</td></tr><tr><td>seeLinkTemplate</td></tr><tr><td>seeListEntryTemplate</td></tr><tr><td>seeListTemplate</td></tr><tr><td>signalsListEntryTemplate</td></tr><tr><td>signalsListTemplate</td></tr><tr><td>sinceInfoTemplate</td></tr>
+<tr><td>authorInfoTemplate</td></tr><tr><td>classTemplate</td></tr><tr><td>constructorTemplate</td></tr><tr><td>deprecatedTemplate</td></tr><tr><td>eventsListEntryTemplate</td></tr><tr><td>eventsListTemplate</td></tr><tr><td>exceptionsListEntryTemplate</td></tr><tr><td>exceptionsListTemplate</td></tr><tr><td>footerTemplate</td></tr><tr><td>functionTemplate</td></tr><tr><td>headerTemplate</td></tr><tr><td>indexBodyTemplate</td></tr><tr><td>indexListEntryTemplate</td></tr><tr><td>indexListModulesTemplate</td></tr><tr><td>indexListPackagesTemplate</td></tr><tr><td>listEntryDeprecatedTemplate</td></tr><tr><td>listEntryNoneTemplate</td></tr><tr><td>listEntrySimpleTemplate</td></tr><tr><td>listEntryTemplate</td></tr><tr><td>listTemplate</td></tr><tr><td>methodTemplate</td></tr><tr><td>moduleTemplate</td></tr><tr><td>paragraphTemplate</td></tr><tr><td>parameterTypesListEntryTemplate</td></tr><tr><td>parametersListEntryTemplate</td></tr><tr><td>parametersListTemplate</td></tr><tr><td>rbFileTemplate</td></tr><tr><td>rbModuleTemplate</td></tr><tr><td>rbModulesClassTemplate</td></tr><tr><td>returnTypesTemplate</td></tr><tr><td>returnsTemplate</td></tr><tr><td>seeLinkTemplate</td></tr><tr><td>seeListEntryTemplate</td></tr><tr><td>seeListTemplate</td></tr><tr><td>signalsListEntryTemplate</td></tr><tr><td>signalsListTemplate</td></tr><tr><td>sinceInfoTemplate</td></tr>
 </table>
 <h3>Classes</h3>
 <table>
--- a/DocumentationTools/ModuleDocumentor.py	Mon May 25 16:28:18 2015 +0200
+++ b/DocumentationTools/ModuleDocumentor.py	Sat May 30 12:38:30 2015 +0200
@@ -100,9 +100,13 @@
             self.paragraphTemplate = TemplatesListsStyleCSS.paragraphTemplate
             self.parametersListTemplate = \
                 TemplatesListsStyleCSS.parametersListTemplate
+            self.parameterTypesListEntryTemplate = \
+                TemplatesListsStyleCSS.parameterTypesListEntryTemplate
             self.parametersListEntryTemplate = \
                 TemplatesListsStyleCSS.parametersListEntryTemplate
             self.returnsTemplate = TemplatesListsStyleCSS.returnsTemplate
+            self.returnTypesTemplate = \
+                TemplatesListsStyleCSS.returnTypesTemplate
             self.exceptionsListTemplate = \
                 TemplatesListsStyleCSS.exceptionsListTemplate
             self.exceptionsListEntryTemplate = \
@@ -161,8 +165,13 @@
             self.parametersListEntryTemplate = \
                 TemplatesListsStyle.parametersListEntryTemplate.format(
                     **colors)
+            self.parameterTypesListEntryTemplate = \
+                TemplatesListsStyle.parameterTypesListEntryTemplate.format(
+                    **colors)
             self.returnsTemplate = \
                 TemplatesListsStyle.returnsTemplate.format(**colors)
+            self.returnTypesTemplate = \
+                TemplatesListsStyle.returnTypesTemplate.format(**colors)
             self.exceptionsListTemplate = \
                 TemplatesListsStyle.exceptionsListTemplate.format(**colors)
             self.exceptionsListEntryTemplate = \
@@ -277,6 +286,8 @@
                        })
         except TagError as e:
             sys.stderr.write(
+                "Error processing {0}.\n".format(self.module.file))
+            sys.stderr.write(
                 "Error in tags of description of module {0}.\n".format(
                     self.module.name))
             sys.stderr.write("{0}\n".format(e))
@@ -427,6 +438,8 @@
                        })
             except TagError as e:
                 sys.stderr.write(
+                    "Error processing {0}.\n".format(self.module.file))
+                sys.stderr.write(
                     "Error in tags of description of class {0}.\n".format(
                         className))
                 sys.stderr.write("{0}\n".format(e))
@@ -509,6 +522,8 @@
                        })
             except TagError as e:
                 sys.stderr.write(
+                    "Error processing {0}.\n".format(self.module.file))
+                sys.stderr.write(
                     "Error in tags of description of method {0}.{1}.\n".format(
                         className, '__init__'))
                 sys.stderr.write("{0}\n".format(e))
@@ -535,6 +550,8 @@
                        })
             except TagError as e:
                 sys.stderr.write(
+                    "Error processing {0}.\n".format(self.module.file))
+                sys.stderr.write(
                     "Error in tags of description of method {0}.{1}.\n".format(
                         className, method))
                 sys.stderr.write("{0}\n".format(e))
@@ -581,6 +598,8 @@
                        })
             except TagError as e:
                 sys.stderr.write(
+                    "Error processing {0}.\n".format(self.module.file))
+                sys.stderr.write(
                     "Error in tags of description of Ruby module {0}.\n"
                     .format(rbModuleName))
                 sys.stderr.write("{0}\n".format(e))
@@ -624,6 +643,8 @@
                        })
             except TagError as e:
                 sys.stderr.write(
+                    "Error processing {0}.\n".format(self.module.file))
+                sys.stderr.write(
                     "Error in tags of description of class {0}.\n".format(
                         className))
                 sys.stderr.write("{0}\n".format(e))
@@ -685,6 +706,8 @@
                        })
             except TagError as e:
                 sys.stderr.write(
+                    "Error processing {0}.\n".format(self.module.file))
+                sys.stderr.write(
                     "Error in tags of description of function {0}.\n".format(
                         funcName))
                 sys.stderr.write("{0}\n".format(e))
@@ -796,21 +819,27 @@
                    }))
         return ''.join(lst)
         
-    def __genParamDescriptionListSection(self, _list, template):
+    def __genParamDescriptionListSection(self, _list):
         """
         Private method to generate the list section of a description.
         
-        @param _list List containing the info for the
-            list section.
-        @param template The template to be used for the list. (string)
-        @return The list section. (string)
+        @param _list list containing the info for the parameter description
+            list section (list of lists with three elements)
+        @return formatted list section (string)
         """
         lst = []
-        for name, lines in _list:
-            lst.append(template.format(
-                **{'Name': name,
-                   'Description': html_uencode('\n'.join(lines)),
-                   }))
+        for name, type_, lines in _list:
+            if type_:
+                lst.append(self.parameterTypesListEntryTemplate.format(
+                    **{'Name': name,
+                       'Type': type_,
+                       'Description': html_uencode('\n'.join(lines)),
+                       }))
+            else:
+                lst.append(self.parametersListEntryTemplate.format(
+                    **{'Name': name,
+                       'Description': html_uencode('\n'.join(lines)),
+                       }))
         return ''.join(lst)
         
     def __formatCrossReferenceEntry(self, entry):
@@ -911,6 +940,7 @@
         paragraphs = []
         paramList = []
         returns = []
+        returnTypes = []
         exceptionDict = {}
         signalDict = {}
         eventDict = {}
@@ -924,6 +954,7 @@
         dlist = descr.splitlines()
         while dlist and not dlist[0]:
             del dlist[0]
+        lastTag = ""
         for ditem in dlist:
             ditem = self.__processInlineTags(ditem)
             desc = ditem.strip()
@@ -931,6 +962,7 @@
                 if desc.startswith(("@param", "@keyparam")):
                     inTagSection = True
                     parts = desc.split(None, 2)
+                    lastTag = parts[0]
                     if len(parts) < 2:
                         raise TagError(
                             "Wrong format in {0} line.\n".format(parts[0]))
@@ -938,21 +970,60 @@
                     if parts[0] == "@keyparam":
                         paramName += '='
                     try:
-                        paramList.append([paramName, [parts[2]]])
+                        paramList.append([paramName, "", [parts[2]]])
                     except IndexError:
-                        paramList.append([paramName, []])
-                    lastItem = paramList[-1][1]
+                        paramList.append([paramName, "", []])
+                    lastItem = paramList[-1][2]
+                elif desc.startswith("@type"):
+                    if lastTag not in ["@param", "@keyparam"]:
+                        raise TagError(
+                            "{0} line must be preceded by a parameter line\n"
+                            .format(parts[0]))
+                    inTagSection = True
+                    parts = desc.split(None, 1)
+                    lastTag = parts[0]
+                    if len(parts) < 2:
+                        raise TagError(
+                            "Wrong format in {0} line.\n".format(parts[0]))
+                    paramList[-1][1] = parts[1]
+                elif desc.startswith("@ptype"):
+                    inTagSection = True
+                    parts = desc.split(None, 2)
+                    lastTag = parts[0]
+                    if len(parts) < 3:
+                        raise TagError(
+                            "Wrong format in {0} line.\n".format(parts[0]))
+                    param, type_ = parts[1:]
+                    for index in range(len(paramList)):
+                        if paramList[index][0] == param:
+                            paramList[index][1] = type_
+                            break
+                    else:
+                        raise TagError(
+                            "Unknow parameter name '{0}' in {1} line.\n"
+                            .format(param, parts[0]))
                 elif desc.startswith(("@return", "@ireturn")):
                     inTagSection = True
                     parts = desc.split(None, 1)
+                    lastTag = parts[0]
                     if len(parts) < 2:
                         raise TagError(
                             "Wrong format in {0} line.\n".format(parts[0]))
                     returns = [parts[1]]
                     lastItem = returns
+                elif desc.startswith("@rtype"):
+                    inTagSection = True
+                    parts = desc.split(None, 1)
+                    lastTag = parts[0]
+                    if len(parts) < 2:
+                        raise TagError(
+                            "Wrong format in {0} line.\n".format(parts[0]))
+                    returnTypes = [parts[1]]
+                    lastItem = returnTypes
                 elif desc.startswith(("@exception", "@throws", "@raise")):
                     inTagSection = True
                     parts = desc.split(None, 2)
+                    lastTag = parts[0]
                     if len(parts) < 2:
                         raise TagError(
                             "Wrong format in {0} line.\n".format(parts[0]))
@@ -964,6 +1035,7 @@
                     lastItem = exceptionDict[excName]
                 elif desc.startswith("@signal"):
                     inTagSection = True
+                    lastTag = desc.split(None, 1)[0]
                     m = _signal(desc, 0)
                     if m is None:
                         raise TagError("Wrong format in @signal line.\n")
@@ -977,6 +1049,7 @@
                     lastItem = signalDict[signalName]
                 elif desc.startswith("@event"):
                     inTagSection = True
+                    lastTag = desc.split(None, 1)[0]
                     m = _event(desc, 0)
                     if m is None:
                         raise TagError(
@@ -992,6 +1065,7 @@
                 elif desc.startswith("@deprecated"):
                     inTagSection = True
                     parts = desc.split(None, 1)
+                    lastTag = parts[0]
                     if len(parts) < 2:
                         raise TagError(
                             "Wrong format in {0} line.\n".format(parts[0]))
@@ -1000,6 +1074,7 @@
                 elif desc.startswith("@author"):
                     inTagSection = True
                     parts = desc.split(None, 1)
+                    lastTag = parts[0]
                     if len(parts) < 2:
                         raise TagError(
                             "Wrong format in {0} line.\n".format(parts[0]))
@@ -1008,6 +1083,7 @@
                 elif desc.startswith("@since"):
                     inTagSection = True
                     parts = desc.split(None, 1)
+                    lastTag = parts[0]
                     if len(parts) < 2:
                         raise TagError(
                             "Wrong format in {0} line.\n".format(parts[0]))
@@ -1016,6 +1092,7 @@
                 elif desc.startswith("@see"):
                     inTagSection = True
                     parts = desc.split(None, 1)
+                    lastTag = parts[0]
                     if len(parts) < 2:
                         raise TagError(
                             "Wrong format in {0} line.\n".format(parts[0]))
@@ -1040,7 +1117,7 @@
         if paramList:
             parameterSect = self.parametersListTemplate.format(
                 **{'Parameters': self.__genParamDescriptionListSection(
-                    paramList, self.parametersListEntryTemplate)})
+                    paramList)})
         else:
             parameterSect = ""
         
@@ -1050,6 +1127,12 @@
         else:
             returnSect = ""
         
+        if returnTypes:
+            returnTypesSect = self.returnTypesTemplate.format(
+                html_uencode('\n'.join(returnTypes)))
+        else:
+            returnTypesSect = ""
+        
         if exceptionDict:
             exceptionSect = self.exceptionsListTemplate.format(
                 **{'Exceptions': self.__genDescriptionListSection(
@@ -1096,10 +1179,10 @@
         else:
             seeSect = ''
         
-        return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}".format(
+        return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}{10}".format(
             deprecatedSect, description, parameterSect, returnSect,
-            exceptionSect, signalSect, eventSect, authorInfoSect,
-            seeSect, sinceInfoSect
+            returnTypesSect, exceptionSect, signalSect, eventSect,
+            authorInfoSect, seeSect, sinceInfoSect,
         )
     
     def getQtHelpKeywords(self):
--- a/DocumentationTools/TemplatesListsStyle.py	Mon May 25 16:28:18 2015 +0200
+++ b/DocumentationTools/TemplatesListsStyle.py	Sat May 30 12:38:30 2015 +0200
@@ -177,6 +177,12 @@
 {{Description}}
 </dd>'''
 
+parameterTypesListEntryTemplate = \
+'''<dt><i>{{Name}}</i> ({{Type}})</dt>
+<dd>
+{{Description}}
+</dd>'''
+
 returnsTemplate = \
 '''<dl>
 <dt>Returns:</dt>
@@ -185,6 +191,14 @@
 </dd>
 </dl>'''
 
+returnTypesTemplate = \
+'''<dl>
+<dt>Return Type:</dt>
+<dd>
+{{0}}
+</dd>
+</dl>'''
+
 exceptionsListTemplate = \
 '''<dl>
 {{Exceptions}}
--- a/DocumentationTools/TemplatesListsStyleCSS.py	Mon May 25 16:28:18 2015 +0200
+++ b/DocumentationTools/TemplatesListsStyleCSS.py	Sat May 30 12:38:30 2015 +0200
@@ -159,6 +159,12 @@
 {Description}
 </dd>'''
 
+parameterTypesListEntryTemplate = \
+'''<dt><i>{Name}</i> ({Type})</dt>
+<dd>
+{Description}
+</dd>'''
+
 returnsTemplate = \
 '''<dl>
 <dt>Returns:</dt>
@@ -167,6 +173,14 @@
 </dd>
 </dl>'''
 
+returnTypesTemplate = \
+'''<dl>
+<dt>Return Type:</dt>
+<dd>
+{0}
+</dd>
+</dl>'''
+
 exceptionsListTemplate = \
 '''<dl>
 {Exceptions}
--- a/README-eric6-doc.rst	Mon May 25 16:28:18 2015 +0200
+++ b/README-eric6-doc.rst	Sat May 30 12:38:30 2015 +0200
@@ -104,7 +104,8 @@
 
 @author author
 
-    This tag is used to name the author of the code. For example:
+    This tag is used to name the author of the code. For example::
+    
     @author Detlev Offenbach <detlev@die-offenbachs.de>
 
 @deprecated description
@@ -116,7 +117,7 @@
 
     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:
+    text. For example::
     
     @event closeEvent Emitted when an editor window is closed.
 
@@ -124,15 +125,19 @@
 
     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:
+    of descriptive text. For example::
     
     @exception ValueError The searched value is not contained in the list.
 
+@ireturn description
+
+    This tag is an alias for the @return tag.
+
 @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:
+    the argument name and one or more lines of descriptive text. For example::
     
     @keyparam extension Optional extension of the source file.
 
@@ -140,9 +145,17 @@
 
     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:
+    For example::
     
-    @param filename Name of the source file.
+    @param filename name of the source file
+
+@ptype name parameter-type
+
+    This tag is used to describe the type of  a function or method argument.
+    It is always followed by the argument name and type. The argument has
+    to be defined already with @param or @keyparam. For example::
+    
+    @ptype filename str
 
 @raise exception description
 
@@ -150,10 +163,18 @@
 
 @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:
+    This tag is used to describe a function or method return value. It can 
+    include one or more lines of descriptive text. For example::
     
-    @return list of description strings
+    @return list of file names
+
+@rtype type
+
+    This tag is used to describe a function or method return type. It should
+    follow an @return tag. For
+    example::
+    
+    @rtype list of str
 
 @see reference
 
@@ -162,44 +183,51 @@
 
     @see "string"
     
-        Adds a text entry of string. No link is generated. eric6-doc distinguishes
-        this form from the others by looking for a double-quote (") as the first
-        character. For example:
+        Adds a text entry of string. No link is generated. eric6-doc
+        distinguishes this form from the others by looking for a double-quote
+        (") as the first character. For example:
 
         @see "eric6-doc readme file"
 
     @see <a href="URL#value">label</a>
     
-        Adds a link as defined by URL#value. eric6-doc distinguishes this form from
-        the others by looking for a less-than symbol (<) as the first character.
-        For example:
+        Adds a link as defined by URL#value. eric6-doc distinguishes this form
+        from the others by looking for a less-than symbol (<) as the first
+        character. For example::
 
         @see <a href="eric6.eric6-doc.html>eric6-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:
+        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 eric6.eric6-doc#main eric6-doc main() function
-        @see eric6.DocumentationTools.ModuleDocumentor#ModuleDocument.__genModuleSection
-            ModuleDocument.__genModuleSection
+        @see eric6.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:
+    text. For example::
     
-    @signal lastEditorClosed Emitted after the last editor window was 
-        closed.
+    @signal lastEditorClosed Emitted after the last editor window was closed.
 
 @throws exception description
 
     This tag is an alias for the @exception tag.
 
+@type parameter-type
+
+    This tag is used to give the type of the parameter just described.
+    It must be preceded by a @param or @keyparam tag. For example::
+    
+    @param filename name of the source file
+    @type str
+
 3. Inline Tags
 --------------
 The inline tags recogized by eric6-doc are:
--- a/changelog	Mon May 25 16:28:18 2015 +0200
+++ b/changelog	Sat May 30 12:38:30 2015 +0200
@@ -34,6 +34,9 @@
      when the project type or file type associations are changed
 - Project Browser
   -- added capability to show imports of a Python script
+- Source Code Documentor
+  -- added tags to describe the type of parameters (@type, @ptype)
+     and return values (@rtype)
 - Task Viewer
   -- added capability to add sub-tasks (i.e. a task hierarchy) for
      manually generated tasks

eric ide

mercurial