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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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 (unused)
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