eric7.Plugins.CheckerPlugins.CodeStyleChecker.DocStyle.DocStyleChecker

Module implementing a checker for documentation string conventions.

Global Attributes

None

Classes

DocStyleChecker Class implementing a checker for documentation string conventions.
DocStyleContext Class implementing the source context.

Functions

None


DocStyleChecker

Class implementing a checker for documentation string conventions.

Derived from

None

Class Attributes

Codes

Class Methods

None

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

None

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.

Up


DocStyleContext

Class implementing the source context.

Derived from

None

Class Attributes

None

Class Methods

None

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

None

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
Up