eric7.Plugins.CheckerPlugins.CodeStyleChecker.DocStyle.DocStyleChecker
Module implementing a checker for documentation string conventions.
Global Attributes
Classes
Functions
DocStyleChecker
Class implementing a checker for documentation string conventions.
Derived from
None
Class Attributes
Class Methods
Methods
| DocStyleChecker |
Constructor |
| __checkBackslashes |
Private method to check, that all docstrings containing backslashes are surrounded by raw triple double quotes. |
| __checkBlankAfterLastParagraph |
Private method to check, that the last paragraph of docstrings is followed by a blank line. |
| __checkBlankAfterSummary |
Private method to check, that docstring summaries are followed by a blank line. |
| __checkBlankBeforeAndAfterClass |
Private method to check, that class docstrings have one blank line around them. |
| __checkClassDocstring |
Private method to check, that all public functions and methods have a docstring. |
| __checkEndsWithPeriod |
Private method to check, that docstring summaries end with a period. |
| __checkEricBlankAfterSummary |
Private method to check, that docstring summaries are followed by a blank line. |
| __checkEricDocumentationDeprecatedTags |
Private method to check the use of deprecated documentation tags. |
| __checkEricDocumentationIndent |
Private method to check the the correct indentation of the tag lines. |
| __checkEricDocumentationSequence |
Private method to check, that method docstring follows the correct sequence of entries (e.g. |
| __checkEricEndsWithPeriod |
Private method to check, that docstring summaries end with a period. |
| __checkEricException |
Private method to check, that docstrings contain an @exception line if they raise an exception and don't otherwise. |
| __checkEricFunctionArguments |
Private method to check, that docstrings contain an @param and/or @keyparam line for each argument. |
| __checkEricNBlankAfterLastParagraph |
Private method to check, that the last paragraph of docstrings is not followed by a blank line. |
| __checkEricNoBlankBeforeAndAfterClassOrFunction |
Private method to check, that class and function/method docstrings have no blank line around them. |
| __checkEricQuotesOnSeparateLines |
Private method to check, that leading and trailing quotes are on a line by themselves. |
| __checkEricReturn |
Private method to check, that docstrings contain an @return line if they return anything and don't otherwise. |
| __checkEricSignal |
Private method to check, that docstrings contain an @signal line if they define signals and don't otherwise. |
| __checkEricSummary |
Private method to check, that method docstring summaries start with specific words. |
| __checkEricYield |
Private method to check, that docstrings contain an @yield line if they return anything and don't otherwise. |
| __checkFunctionDocstring |
Private method to check, that all public functions and methods have a docstring. |
| __checkImperativeMood |
Private method to check, that docstring summaries are in imperative mood. |
| __checkIndent |
Private method to check, that docstrings are properly indented. |
| __checkModulesDocstrings |
Private method to check, if the module has a docstring. |
| __checkNoBlankLineBefore |
Private method to check, that function/method docstrings are not preceded by a blank line. |
| __checkNoSignature |
Private method to check, that docstring summaries don't repeat the function's signature. |
| __checkOneLiner |
Private method to check, that one-liner docstrings fit on one line with quotes. |
| __checkReturnType |
Private method to check, that docstrings mention the return value type. |
| __checkSummary |
Private method to check, that docstring summaries contain some text. |
| __checkTripleDoubleQuotes |
Private method to check, that all docstrings are surrounded by triple double quotes. |
| __error |
Private method to record an issue. |
| __getArgNames |
Private method to get the argument names of a function node. |
| __getSummaryLine |
Private method to extract the summary line. |
| __getSummaryLines |
Private method to extract the summary lines. |
| __ignoreCode |
Private method to check if the error code should be ignored. |
| __parseClasses |
Private method to extract top-level classes. |
| __parseContexts |
Private method to extract a context from the source. |
| __parseDocstring |
Private method to extract a docstring given `def` or `class` source. |
| __parseFunctions |
Private method to extract top-level functions. |
| __parseMethods |
Private method to extract methods of all classes. |
| __parseModuleDocstring |
Private method to extract a docstring given a module source. |
| __parseTopLevel |
Private method to extract top-level functions or classes. |
| __readline |
Private method to get the next line from the source. |
| __resetReadline |
Private method to reset the internal readline function. |
| __skipIndentedBlock |
Private method to skip over an indented block of source code. |
| run |
Public method to check the given source for violations of doc string conventions. |
Static Methods
DocStyleChecker (Constructor)
DocStyleChecker(source, filename, select, ignore, expected, repeat, maxLineLength=88, docType="pep257", )
Constructor
- source (list of str)
-
source code to be checked
- filename (str)
-
name of the source file
- select (list of str)
-
list of selected codes
- ignore (list of str)
-
list of codes to be ignored
- expected (list of str)
-
list of expected codes
- repeat (bool)
-
flag indicating to report each occurrence of a code
- maxLineLength (int)
-
allowed line length
- docType (str)
-
type of the documentation strings (one of 'eric' or 'pep257')
DocStyleChecker.__checkBackslashes
__checkBackslashes(docstringContext, context)
Private method to check, that all docstrings containing
backslashes are surrounded by raw triple double quotes.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkBlankAfterLastParagraph
__checkBlankAfterLastParagraph(docstringContext, context)
Private method to check, that the last paragraph of docstrings is
followed by a blank line.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkBlankAfterSummary
__checkBlankAfterSummary(docstringContext, context)
Private method to check, that docstring summaries are followed
by a blank line.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkBlankBeforeAndAfterClass
__checkBlankBeforeAndAfterClass(docstringContext, context)
Private method to check, that class docstrings have one
blank line around them.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkClassDocstring
__checkClassDocstring(docstringContext, context)
Private method to check, that all public functions and methods
have a docstring.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEndsWithPeriod
__checkEndsWithPeriod(docstringContext, context)
Private method to check, that docstring summaries end with a period.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricBlankAfterSummary
__checkEricBlankAfterSummary(docstringContext, context)
Private method to check, that docstring summaries are followed
by a blank line.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricDocumentationDeprecatedTags
__checkEricDocumentationDeprecatedTags(docstringContext, context, )
Private method to check the use of deprecated documentation tags.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricDocumentationIndent
__checkEricDocumentationIndent(docstringContext, context, )
Private method to check the the correct indentation of the tag lines.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricDocumentationSequence
__checkEricDocumentationSequence(docstringContext, context, )
Private method to check, that method docstring follows the correct sequence
of entries (e.g. @param is followed by @type).
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricEndsWithPeriod
__checkEricEndsWithPeriod(docstringContext, context)
Private method to check, that docstring summaries end with a period.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricException
__checkEricException(docstringContext, context)
Private method to check, that docstrings contain an @exception line
if they raise an exception and don't otherwise.
Note: This method also checks the raised and documented exceptions for
completeness (i.e. raised exceptions that are not documented or
documented exceptions that are not raised)
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricFunctionArguments
__checkEricFunctionArguments(docstringContext, context)
Private method to check, that docstrings contain an @param and/or
@keyparam line for each argument.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricNBlankAfterLastParagraph
__checkEricNBlankAfterLastParagraph(docstringContext, context)
Private method to check, that the last paragraph of docstrings is
not followed by a blank line.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricNoBlankBeforeAndAfterClassOrFunction
__checkEricNoBlankBeforeAndAfterClassOrFunction(docstringContext, context)
Private method to check, that class and function/method docstrings
have no blank line around them.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricQuotesOnSeparateLines
__checkEricQuotesOnSeparateLines(docstringContext, context)
Private method to check, that leading and trailing quotes are on
a line by themselves.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricReturn
__checkEricReturn(docstringContext, context)
Private method to check, that docstrings contain an @return line
if they return anything and don't otherwise.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricSignal
__checkEricSignal(docstringContext, context)
Private method to check, that docstrings contain an @signal line
if they define signals and don't otherwise.
Note: This method also checks the defined and documented signals for
completeness (i.e. defined signals that are not documented or
documented signals that are not defined)
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricSummary
__checkEricSummary(docstringContext, context)
Private method to check, that method docstring summaries start with
specific words.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkEricYield
__checkEricYield(docstringContext, context)
Private method to check, that docstrings contain an @yield line
if they return anything and don't otherwise.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkFunctionDocstring
__checkFunctionDocstring(docstringContext, context)
Private method to check, that all public functions and methods
have a docstring.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkImperativeMood
__checkImperativeMood(docstringContext, context)
Private method to check, that docstring summaries are in
imperative mood.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkIndent
__checkIndent(docstringContext, context)
Private method to check, that docstrings are properly indented.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkModulesDocstrings
__checkModulesDocstrings(docstringContext, context)
Private method to check, if the module has a docstring.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkNoBlankLineBefore
__checkNoBlankLineBefore(docstringContext, context)
Private method to check, that function/method docstrings are not
preceded by a blank line.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkNoSignature
__checkNoSignature(docstringContext, context)
Private method to check, that docstring summaries don't repeat
the function's signature.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkOneLiner
__checkOneLiner(docstringContext, context)
Private method to check, that one-liner docstrings fit on
one line with quotes.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkReturnType
__checkReturnType(docstringContext, context)
Private method to check, that docstrings mention the return value type.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkSummary
__checkSummary(docstringContext, context)
Private method to check, that docstring summaries contain some text.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__checkTripleDoubleQuotes
__checkTripleDoubleQuotes(docstringContext, context)
Private method to check, that all docstrings are surrounded
by triple double quotes.
- docstringContext (DocStyleContext)
-
docstring context
- context (DocStyleContext)
-
context of the docstring
DocStyleChecker.__error
__error(lineNumber, offset, code, *args)
Private method to record an issue.
- lineNumber (int)
-
line number of the issue
- offset (int)
-
position within line of the issue
- code (str)
-
message code
- args (list)
-
arguments for the message
DocStyleChecker.__getArgNames
__getArgNames(node)
Private method to get the argument names of a function node.
- node (ast.AST)
-
AST node to extract arguments names from
- Return:
-
tuple of two list of argument names, one for arguments
and one for keyword arguments
- Return Type:
-
tuple of (list of str, list of str)
DocStyleChecker.__getSummaryLine
__getSummaryLine(docstringContext)
Private method to extract the summary line.
- docstringContext (DocStyleContext)
-
docstring context
- Return:
-
summary line (string) and the line it was found on
- Return Type:
-
int
DocStyleChecker.__getSummaryLines
__getSummaryLines(docstringContext)
Private method to extract the summary lines.
- docstringContext (DocStyleContext)
-
docstring context
- Return:
-
summary lines (list of string) and the line it was found on
- Return Type:
-
int
DocStyleChecker.__ignoreCode
__ignoreCode(code)
Private method to check if the error code should be ignored.
- code (str)
-
message code to check for
- Return:
-
flag indicating to ignore the given code
- Return Type:
-
bool
DocStyleChecker.__parseClasses
__parseClasses()
Private method to extract top-level classes.
- Return:
-
extracted class contexts
- Return Type:
-
list of DocStyleContext
DocStyleChecker.__parseContexts
__parseContexts(kind)
Private method to extract a context from the source.
- kind (str)
-
kind of context to extract
- Return:
-
requested contexts
- Return Type:
-
list of DocStyleContext
DocStyleChecker.__parseDocstring
__parseDocstring(context, what="")
Private method to extract a docstring given `def` or `class` source.
- context (DocStyleContext)
-
context data to get the docstring from
- what (str)
-
string denoting what is being parsed
- Return:
-
context of extracted docstring
- Return Type:
-
DocStyleContext
DocStyleChecker.__parseFunctions
__parseFunctions()
Private method to extract top-level functions.
- Return:
-
extracted function contexts
- Return Type:
-
list of DocStyleContext
DocStyleChecker.__parseMethods
__parseMethods()
Private method to extract methods of all classes.
- Return:
-
extracted method contexts
- Return Type:
-
list of DocStyleContext
DocStyleChecker.__parseModuleDocstring
__parseModuleDocstring(source)
Private method to extract a docstring given a module source.
- source (list of str)
-
source to parse
- Return:
-
context of extracted docstring
- Return Type:
-
DocStyleContext
DocStyleChecker.__parseTopLevel
__parseTopLevel(keyword)
Private method to extract top-level functions or classes.
- keyword (str)
-
keyword signaling what to extract
- Return:
-
extracted function or class contexts
- Return Type:
-
list of DocStyleContext
DocStyleChecker.__readline
__readline()
Private method to get the next line from the source.
- Return:
-
next line of source
- Return Type:
-
str
DocStyleChecker.__resetReadline
__resetReadline()
Private method to reset the internal readline function.
DocStyleChecker.__skipIndentedBlock
__skipIndentedBlock(tokenGenerator)
Private method to skip over an indented block of source code.
- tokenGenerator (str iterator)
-
token generator
- Return:
-
last token of the indented block
- Return Type:
-
tuple
DocStyleChecker.run
run()
Public method to check the given source for violations of doc string
conventions.
DocStyleContext
Class implementing the source context.
Derived from
None
Class Attributes
Class Methods
Methods
| DocStyleContext |
Constructor |
| contextType |
Public method to get the context type. |
| end |
Public method to get the end line number. |
| indent |
Public method to get the indentation of the first line. |
| setSpecial |
Public method to set a special attribute for the context. |
| source |
Public method to get the source. |
| special |
Public method to get the special context attribute string. |
| ssource |
Public method to get the joined source lines. |
| start |
Public method to get the start line number. |
Static Methods
DocStyleContext (Constructor)
DocStyleContext(source, startLine, contextType)
Constructor
- source (list of str or str)
-
source code of the context
- startLine (int)
-
line number the context starts in the source
- contextType (str)
-
type of the context object
DocStyleContext.contextType
contextType()
Public method to get the context type.
- Return:
-
context type
- Return Type:
-
str
DocStyleContext.end
end()
Public method to get the end line number.
- Return:
-
end line number
- Return Type:
-
int
DocStyleContext.indent
indent()
Public method to get the indentation of the first line.
- Return:
-
indentation string
- Return Type:
-
str
DocStyleContext.setSpecial
setSpecial(special)
Public method to set a special attribute for the context.
- special (str)
-
attribute string
DocStyleContext.source
source()
Public method to get the source.
- Return:
-
source
- Return Type:
-
list of str
DocStyleContext.special
special()
Public method to get the special context attribute string.
- Return:
-
attribute string
- Return Type:
-
str
DocStyleContext.ssource
ssource()
Public method to get the joined source lines.
- Return:
-
source
- Return Type:
-
str
DocStyleContext.start
start()
Public method to get the start line number.
- Return:
-
start line number
- Return Type:
-
int