--- a/src/eric7/DocumentationTools/ModuleDocumentor.py Sun Dec 17 17:15:19 2023 +0100
+++ b/src/eric7/DocumentationTools/ModuleDocumentor.py Mon Dec 18 16:39:01 2023 +0100
@@ -88,8 +88,9 @@
Public method to determine, if the module contains any classes or
functions.
- @return Flag indicating an empty module (i.e. __init__.py without
+ @return flag indicating an empty module (i.e. __init__.py without
any contents)
+ @rtype bool
"""
return self.empty
@@ -97,7 +98,8 @@
"""
Public method used to get the module name.
- @return The name of the module. (string)
+ @return name of the module
+ @rtype str
"""
return self.module.name
@@ -105,7 +107,8 @@
"""
Public method used to get the description of the module.
- @return The description of the module. (string)
+ @return description of the module
+ @rtype str
"""
return self.__formatDescription(self.module.description)
@@ -116,7 +119,8 @@
The short description is just the first line of the modules
description.
- @return The short description of the module. (string)
+ @return short description of the module
+ @rtype str
"""
return self.__getShortDescription(self.module.description)
@@ -124,7 +128,8 @@
"""
Public method to generate the source code documentation.
- @return The source code documentation. (string)
+ @return source code documentation
+ @rtype str
"""
doc = (
TemplatesListsStyleCSS.headerTemplate.format(**{"Title": self.module.name})
@@ -138,7 +143,8 @@
"""
Private method to generate the body of the document.
- @return The body of the document. (string)
+ @return body of the document
+ @rtype str
"""
globalsList = self.__genGlobalsListSection()
classList = self.__genClassListSection()
@@ -191,11 +197,14 @@
"""
Private method to generate a list section of the document.
- @param names The names to appear in the list. (list of strings)
+ @param names names to appear in the list
+ @type list of str
@param sectionDict dictionary containing all relevant information
- (dict)
- @param kwSuffix suffix to be used for the QtHelp keywords (string)
- @return list section (string)
+ @type dict
+ @param kwSuffix suffix to be used for the QtHelp keywords
+ @type str
+ @return list section
+ @rtype str
"""
lst = []
for name in names:
@@ -224,8 +233,10 @@
Private method to generate the section listing all global attributes of
the module.
- @param class_ reference to a class object (Class)
- @return The globals list section. (string)
+ @param class_ reference to a class object
+ @type class
+ @return globals list section
+ @rtype str
"""
attrNames = []
scope = class_ if class_ is not None else self.module
@@ -251,7 +262,8 @@
Private method to generate the section listing all classes of the
module.
- @return The classes list section. (string)
+ @return classes list section
+ @rtype str
"""
names = sorted(self.module.classes)
if names:
@@ -266,7 +278,8 @@
Private method to generate the section listing all modules of the file
(Ruby only).
- @return The modules list section. (string)
+ @return modules list section
+ @rtype str
"""
names = sorted(self.module.modules)
if names:
@@ -281,7 +294,8 @@
Private method to generate the section listing all functions of the
module.
- @return The functions list section. (string)
+ @return functions list section
+ @rtype str
"""
names = sorted(self.module.functions)
if names:
@@ -296,7 +310,8 @@
Private method to generate the document section with details about
classes.
- @return The classes details section. (string)
+ @return classes details section
+ @rtype str
"""
classNames = sorted(self.module.classes)
classes = []
@@ -352,14 +367,18 @@
"""
Private method to generate the methods list section of a class.
- @param names names to appear in the list (list of strings)
+ @param names names to appear in the list
+ @type list of str
@param sectionDict dictionary containing all relevant information
- (dict)
+ @type dict
@param className class name containing the names
+ @type str
@param clsName visible class name containing the names
+ @type str
@param includeInit flag indicating to include the __init__ method
- (boolean)
- @return methods list section (string)
+ @type bool
+ @return methods list section
+ @rtype str
"""
lst = []
if includeInit:
@@ -414,9 +433,13 @@
Private method to generate the method details section.
@param obj reference to the object being formatted
- @param className name of the class containing the method (string)
+ @type class
+ @param className name of the class containing the method
+ @type str
@param modifierFilter filter value designating the method types
- @return method list and method details section (tuple of two string)
+ @type str
+ @return method list and method details section
+ @rtype tuple of (str, str)
"""
methList = []
methBodies = []
@@ -499,7 +522,8 @@
Private method to generate the document section with details about
Ruby modules.
- @return The Ruby modules details section. (string)
+ @return Ruby modules details section
+ @rtype str
"""
rbModulesNames = sorted(self.module.modules)
rbModules = []
@@ -546,10 +570,12 @@
"""
Private method to generate the Ruby module classes details section.
- @param obj Reference to the object being formatted.
- @param modName Name of the Ruby module containing the classes. (string)
- @return The classes list and classes details section.
- (tuple of two string)
+ @param obj reference to the object being formatted
+ @type class
+ @param modName name of the Ruby module containing the classes
+ @type str
+ @return classes list and classes details section
+ @rtype tuple of (str, str)
"""
classNames = sorted(obj.classes)
classes = []
@@ -600,12 +626,14 @@
"""
Private method to generate the classes list section of a Ruby module.
- @param names The names to appear in the list. (list of strings)
+ @param names names to appear in the list
+ @type list of str
@param sectionDict dictionary containing all relevant information
- (dict)
+ @type dict
@param moduleName name of the Ruby module containing the classes
- (string)
- @return The list section. (string)
+ @type str
+ @return list section
+ @rtype str
"""
lst = []
for name in names:
@@ -638,7 +666,8 @@
Private method to generate the document section with details about
functions.
- @return The functions details section. (string)
+ @return functions details section
+ @rtype str
"""
funcBodies = []
funcNames = sorted(self.module.functions)
@@ -673,8 +702,10 @@
The short description is just the first non empty line of the
documentation string.
- @param desc The documentation string. (string)
- @return The short description. (string)
+ @param desc documentation string
+ @type str
+ @return short description
+ @rtype str
"""
dlist = desc.splitlines()
sdlist = []
@@ -711,8 +742,10 @@
Private method to check, if the object to be documented contains a
deprecated flag.
- @param descr documentation string (string)
- @return flag indicating the deprecation status (boolean)
+ @param descr documentation string
+ @type str
+ @return flag indicating the deprecation status
+ @rtype bool
"""
dlist = descr.splitlines()
for desc in dlist:
@@ -729,8 +762,10 @@
an intermediate empty line. Empty lines are treated as a paragraph
delimiter.
- @param lines A list of individual lines. (list of strings)
- @return Ready formatted paragraphs. (string)
+ @param lines list of individual lines
+ @type list of str
+ @return formatted paragraphs
+ @rtype str
"""
lst = []
linelist = []
@@ -759,10 +794,13 @@
"""
Private method to generate the list section of a description.
- @param dictionary Dictionary containing the info for the
- list section.
- @param template The template to be used for the list. (string)
- @return The list section. (string)
+ @param dictionary dictionary containing the info for the
+ list section
+ @type dict
+ @param template template to be used for the list
+ @type str
+ @return list section
+ @rtype str
"""
lst = []
keys = sorted(dictionary)
@@ -782,8 +820,10 @@
Private method to generate the list section of a description.
@param _list list containing the info for the parameter description
- list section (list of lists with three elements)
- @return formatted list section (string)
+ list section
+ @type list of lists with three elements
+ @return formatted list section
+ @rtype str
"""
lst = []
for name, type_, lines in _list:
@@ -814,8 +854,10 @@
This cross reference entry looks like "package.module#member label".
- @param entry the entry to be formatted (string)
- @return formatted entry (string)
+ @param entry entry to be formatted
+ @type str
+ @return formatted entry
+ @rtype str
"""
if entry.startswith('"'):
return entry
@@ -844,9 +886,12 @@
Private method to generate the "see also" list section of a
description.
- @param _list List containing the info for the 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 section
+ @type list
+ @param template template to be used for the list
+ @type str
+ @return list section
+ @rtype str
"""
lst = []
for seeEntry in _list:
@@ -866,8 +911,10 @@
"""
Private method to process inline tags.
- @param desc One line of the description (string)
- @return processed line with inline tags expanded (string)
+ @param desc one line of the description
+ @type str
+ @return processed line with inline tags expanded
+ @rtype str
@exception TagError raised to indicate an invalid tag
"""
start = desc.find("{@")
@@ -900,10 +947,11 @@
"""
Private method to format the contents of the documentation string.
- @param descr The contents of the documentation string. (string)
- @exception TagError A tag doesn't have the correct number
- of arguments.
- @return The formatted contents of the documentation string. (string)
+ @param descr contents of the documentation string
+ @type str
+ @return formatted contents of the documentation string
+ @rtype str
+ @exception TagError A tag doesn't have the correct number of arguments.
"""
if not descr:
return ""
@@ -967,23 +1015,12 @@
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")):
+ raise TagError("Tag '@ptype' is deprecated, use '@type' instead\n")
+ elif desc.startswith("@ireturn"):
+ raise TagError(
+ "Tag '@ireturn' is deprecated, use '@return' instead\n"
+ )
+ elif desc.startswith("@return"):
inTagSection = True
parts = desc.split(None, 1)
lastTag = parts[0]
@@ -993,7 +1030,7 @@
lastItem = returns
elif desc.startswith("@rtype"):
parts = desc.split(None, 1)
- if lastTag not in ["@return", "@ireturn"]:
+ if lastTag != "@return":
raise TagError(
"{0} line must be preceded by a @return line\n".format(
parts[0]
@@ -1027,7 +1064,14 @@
raise TagError("Wrong format in {0} line.\n".format(parts[0]))
yieldTypes = [parts[1]]
lastItem = yieldTypes
- elif desc.startswith(("@exception", "@throws", "@raise")):
+ elif desc.startswith(("@throws", "@raise")):
+ tag = desc.split(None, 1)[0]
+ raise TagError(
+ "Tag '{0}' is deprecated, use '@exception' instead\n".format(
+ tag
+ )
+ )
+ elif desc.startswith("@exception"):
inTagSection = True
parts = desc.split(None, 2)
lastTag = parts[0]
@@ -1250,8 +1294,9 @@
"""
Public method to retrieve the parts for the QtHelp keywords section.
- @return list of tuples containing the name (string) and the ref
- (string). The ref is without the filename part.
+ @return list of tuples containing the name and the ref. The ref is without
+ the filename part.
+ @rtype list of tuples of (str, str)
"""
if not self.generated:
self.genDocument()
