eric: comparison src/eric7/DocumentationTools/ModuleDocumentor.py

-:c6011e501282
+:4573827e9815
 def isEmpty(self):
 """
 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
 def name(self):
 """
 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
 def description(self):
 """
 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)
 def shortDescription(self):
 """
 Public method used to get the short description of the module.
 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)
 def genDocument(self):
 """
 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})
 + self.__genModuleSection()
 + TemplatesListsStyleCSS.footerTemplate
 def __genModuleSection(self):
 """
 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()
 functionList = self.__genFunctionListSection()
 try:
 def __genListSection(self, names, sectionDict, kwSuffix=""):
 """
 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)
+@type dict
-@param kwSuffix suffix to be used for the QtHelp keywords (string)
+@param kwSuffix suffix to be used for the QtHelp keywords
-@return list section (string)
+@type str
+@return list section
+@rtype str
 """
 lst = []
 for name in names:
 lst.append(
 TemplatesListsStyleCSS.listEntryTemplate.format(
 def __genGlobalsListSection(self, class_=None):
 """
 Private method to generate the section listing all global attributes of
 the module.
-@param class_ reference to a class object (Class)
+@param class_ reference to a class object
-@return The globals list section. (string)
+@type class
+@return globals list section
+@rtype str
 """
 attrNames = []
 scope = class_ if class_ is not None else self.module
 attrNames = sorted(
 attr for attr in scope.globals if not scope.globals[attr].isSignal
 def __genClassListSection(self):
 """
 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:
 self.empty = False
 s = self.__genListSection(names, self.module.classes)
 def __genRbModulesListSection(self):
 """
 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:
 self.empty = False
 s = self.__genListSection(names, self.module.modules)
 def __genFunctionListSection(self):
 """
 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:
 self.empty = False
 s = self.__genListSection(names, self.module.functions)
 def __genClassesSection(self):
 """
 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 = []
 for className in classNames:
 _class = self.module.classes[className]
 self, names, sectionDict, className, clsName, includeInit=True
 ):
 """
 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)
+@type bool
-@return methods list section (string)
+@return methods list section
+@rtype str
 """
 lst = []
 if includeInit:
 with contextlib.suppress(KeyError):
 lst.append(
 def __genMethodSection(self, obj, className, modifierFilter):
 """
 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 = []
 methods = sorted(
 k for k in obj.methods if obj.methods[k].modifier == modifierFilter
 def __genRbModulesSection(self):
 """
 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 = []
 for rbModuleName in rbModulesNames:
 rbModule = self.module.modules[rbModuleName]
 def __genRbModulesClassesSection(self, obj, modName):
 """
 Private method to generate the Ruby module classes details section.
-@param obj Reference to the object being formatted.
+@param obj reference to the object being formatted
-@param modName Name of the Ruby module containing the classes. (string)
+@type class
-@return The classes list and classes details section.
+@param modName name of the Ruby module containing the classes
-(tuple of two string)
+@type str
+@return classes list and classes details section
+@rtype tuple of (str, str)
 """
 classNames = sorted(obj.classes)
 classes = []
 for className in classNames:
 _class = obj.classes[className]
 def __genRbModulesClassesListSection(self, names, sectionDict, moduleName):
 """
 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)
+@type str
-@return The list section. (string)
+@return list section
+@rtype str
 """
 lst = []
 for name in names:
 lst.append(
 TemplatesListsStyleCSS.listEntryTemplate.format(
 def __genFunctionsSection(self):
 """
 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)
 for funcName in funcNames:
 try:
 Private method to determine the short description of an object.
 The short description is just the first non empty line of the
 documentation string.
-@param desc The documentation string. (string)
+@param desc documentation string
-@return The short description. (string)
+@type str
+@return short description
+@rtype str
 """
 dlist = desc.splitlines()
 sdlist = []
 descfound = 0
 for desc in dlist:
 def __checkDeprecated(self, descr):
 """
 Private method to check, if the object to be documented contains a
 deprecated flag.
-@param descr documentation string (string)
+@param descr documentation string
-@return flag indicating the deprecation status (boolean)
+@type str
+@return flag indicating the deprecation status
+@rtype bool
 """
 dlist = descr.splitlines()
 for desc in dlist:
 desc = desc.strip()
 if desc.startswith("@deprecated"):
 A paragraph is made up of a number of consecutive lines without
 an intermediate empty line. Empty lines are treated as a paragraph
 delimiter.
-@param lines A list of individual lines. (list of strings)
+@param lines list of individual lines
-@return Ready formatted paragraphs. (string)
+@type list of str
+@return formatted paragraphs
+@rtype str
 """
 lst = []
 linelist = []
 for line in lines:
 if line.strip():
 def __genDescriptionListSection(self, dictionary, template):
 """
 Private method to generate the list section of a description.
-@param dictionary Dictionary containing the info for the
+@param dictionary dictionary containing the info for the
-list section.
+list section
-@param template The template to be used for the list. (string)
+@type dict
-@return The list section. (string)
+@param template template to be used for the list
+@type str
+@return list section
+@rtype str
 """
 lst = []
 keys = sorted(dictionary)
 for key in keys:
 lst.append(
 def __genParamDescriptionListSection(self, _list):
 """
 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)
+list section
-@return formatted list section (string)
+@type list of lists with three elements
+@return formatted list section
+@rtype str
 """
 lst = []
 for name, type_, lines in _list:
 if type_:
 lst.append(
 """
 Private method to format a cross reference entry.
 This cross reference entry looks like "package.module#member label".
-@param entry the entry to be formatted (string)
+@param entry entry to be formatted
-@return formatted entry (string)
+@type str
+@return formatted entry
+@rtype str
 """
 if entry.startswith('"'):
 return entry
 elif entry.startswith("<"):
 entry = entry[3:]
 def __genSeeListSection(self, _list, template):
 """
 Private method to generate the "see also" list section of a
 description.
-@param _list List containing the info for the section.
+@param _list list containing the info for the section
-@param template The template to be used for the list. (string)
+@type list
-@return The list section. (string)
+@param template template to be used for the list
+@type str
+@return list section
+@rtype str
 """
 lst = []
 for seeEntry in _list:
 seeEntryString = "".join(seeEntry)
 lst.append(
 def __processInlineTags(self, desc):
 """
 Private method to process inline tags.
-@param desc One line of the description (string)
+@param desc one line of the description
-@return processed line with inline tags expanded (string)
+@type str
+@return processed line with inline tags expanded
+@rtype str
 @exception TagError raised to indicate an invalid tag
 """
 start = desc.find("{@")
 while start != -1:
 stop = desc.find("}", start + 2)
 def __formatDescription(self, descr):
 """
 Private method to format the contents of the documentation string.
-@param descr The contents of the documentation string. (string)
+@param descr contents of the documentation string
-@exception TagError A tag doesn't have the correct number
+@type str
-of arguments.
+@return formatted contents of the documentation string
-@return The formatted contents of the documentation string. (string)
+@rtype str
+@exception TagError A tag doesn't have the correct number of arguments.
 """
 if not descr:
 return ""
 paragraphs = []
 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
+raise TagError("Tag '@ptype' is deprecated, use '@type' instead\n")
-parts = desc.split(None, 2)
+elif desc.startswith("@ireturn"):
-lastTag = parts[0]
+raise TagError(
-if len(parts) < 3:
+"Tag '@ireturn' is deprecated, use '@return' instead\n"
-raise TagError("Wrong format in {0} line.\n".format(parts[0]))
+)
-param, type_ = parts[1:]
+elif desc.startswith("@return"):
-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"):
 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]
 )
 )
 lastTag = parts[0]
 if len(parts) < 2:
 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]
 if len(parts) < 2:
 raise TagError("Wrong format in {0} line.\n".format(parts[0]))
 def getQtHelpKeywords(self):
 """
 Public method to retrieve the parts for the QtHelp keywords section.
-@return list of tuples containing the name (string) and the ref
+@return list of tuples containing the name and the ref. The ref is without
-(string). The ref is without the filename part.
+the filename part.
+@rtype list of tuples of (str, str)
 """
 if not self.generated:
 self.genDocument()
 return self.keywords

Mercurial Repositories > eric / file comparison

comparison: src/eric7/DocumentationTools/ModuleDocumentor.py

src/eric7/DocumentationTools/ModuleDocumentor.py