eric5.Plugins.CheckerPlugins.CodeStyleChecker.DocStyleChecker

Module implementing a checker for documentation string conventions.

Global Attributes

PyCF_ONLY_AST

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

object

Class Attributes

Codes

Messages

MessagesSampleArgs

Class Methods

getMessage

Class method to get a translated and formatted message for a given code.

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.
__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.
__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.
__checkUnicode	Private method to check, that all docstrings containing unicode characters are surrounded by unicode triple double quotes.
__error	Private method to record an issue.
__getArgNames
__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.
__reportInvalidSyntax	Private method to report a syntax error.
__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.
unpackArgs	Local helper function to unpack function argument names.

Static Methods

None

DocStyleChecker.getMessage (class method)

getMessage(code, *args)

Class method to get a translated and formatted message for a given code.

code: message code (string)
args: arguments for a formatted message (list)

Returns:: translated and formatted message (string)

DocStyleChecker (Constructor)

DocStyleChecker(source, filename, select, ignore, expected, repeat, maxLineLength=79, docType="pep257")

Constructor

source: source code to be checked (list of string)
filename: name of the source file (string)
select: list of selected codes (list of string)
ignore: list of codes to be ignored (list of string)
expected: list of expected codes (list of string)
repeat: flag indicating to report each occurrence of a code (boolean)
maxLineLength=: allowed line length (integer)
docType=: type of the documentation strings (string, 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: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkBlankAfterLastParagraph

__checkBlankAfterLastParagraph(docstringContext, context)

Private method to check, that the last paragraph of docstrings is followed by a blank line.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkBlankAfterSummary

__checkBlankAfterSummary(docstringContext, context)

Private method to check, that docstring summaries are followed by a blank line.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkBlankBeforeAndAfterClass

__checkBlankBeforeAndAfterClass(docstringContext, context)

Private method to check, that class docstrings have one blank line around them.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkClassDocstring

__checkClassDocstring(docstringContext, context)

Private method to check, that all public functions and methods have a docstring.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEndsWithPeriod

__checkEndsWithPeriod(docstringContext, context)

Private method to check, that docstring summaries end with a period.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEricBlankAfterSummary

__checkEricBlankAfterSummary(docstringContext, context)

Private method to check, that docstring summaries are followed by a blank line.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEricEndsWithPeriod

__checkEricEndsWithPeriod(docstringContext, context)

Private method to check, that docstring summaries end with a period.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEricException

__checkEricException(docstringContext, context)

Private method to check, that docstrings contain an @exception line if they raise an exception and don't otherwise.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEricFunctionArguments

__checkEricFunctionArguments(docstringContext, context)

Private method to check, that docstrings contain an @param and/or @keyparam line for each argument.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEricNBlankAfterLastParagraph

__checkEricNBlankAfterLastParagraph(docstringContext, context)

Private method to check, that the last paragraph of docstrings is not followed by a blank line.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEricNoBlankBeforeAndAfterClassOrFunction

__checkEricNoBlankBeforeAndAfterClassOrFunction(docstringContext, context)

Private method to check, that class and function/method docstrings have no blank line around them.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEricQuotesOnSeparateLines

__checkEricQuotesOnSeparateLines(docstringContext, context)

Private method to check, that leading and trailing quotes are on a line by themselves.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkEricReturn

__checkEricReturn(docstringContext, context)

Private method to check, that docstrings contain an @return line if they return anything and don't otherwise.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkFunctionDocstring

__checkFunctionDocstring(docstringContext, context)

Private method to check, that all public functions and methods have a docstring.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkImperativeMood

__checkImperativeMood(docstringContext, context)

Private method to check, that docstring summaries are in imperative mood.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkIndent

__checkIndent(docstringContext, context)

Private method to check, that docstrings are properly indented.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkModulesDocstrings

__checkModulesDocstrings(docstringContext, context)

Private method to check, if the module has a docstring.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkNoBlankLineBefore

__checkNoBlankLineBefore(docstringContext, context)

Private method to check, that function/method docstrings are not preceded by a blank line.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkNoSignature

__checkNoSignature(docstringContext, context)

Private method to check, that docstring summaries don't repeat the function's signature.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkOneLiner

__checkOneLiner(docstringContext, context)

Private method to check, that one-liner docstrings fit on one line with quotes.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkReturnType

__checkReturnType(docstringContext, context)

Private method to check, that docstrings mention the return value type.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkSummary

__checkSummary(docstringContext, context)

Private method to check, that docstring summaries contain some text.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkTripleDoubleQuotes

__checkTripleDoubleQuotes(docstringContext, context)

Private method to check, that all docstrings are surrounded by triple double quotes.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__checkUnicode

__checkUnicode(docstringContext, context)

Private method to check, that all docstrings containing unicode characters are surrounded by unicode triple double quotes.

docstringContext: docstring context (DocStyleContext)
context: context of the docstring (DocStyleContext)

DocStyleChecker.__error

__error(lineNumber, offset, code, *args)

Private method to record an issue.

lineNumber: line number of the issue (integer)
offset: position within line of the issue (integer)
code: message code (string)
args: arguments for the message (list)

DocStyleChecker.__getArgNames

__getArgNames(node)

DocStyleChecker.__getSummaryLine

__getSummaryLine(docstringContext)

Private method to extract the summary line.

docstringContext: docstring context (DocStyleContext)

Returns:: summary line (string) and the line it was found on (integer)

DocStyleChecker.__getSummaryLines

__getSummaryLines(docstringContext)

Private method to extract the summary lines.

docstringContext: docstring context (DocStyleContext)

Returns:: summary lines (list of string) and the line it was found on (integer)

DocStyleChecker.__ignoreCode

__ignoreCode(code)

Private method to check if the error code should be ignored.

code: message code to check for (string)

Returns:: flag indicating to ignore the given code (boolean)

DocStyleChecker.__parseClasses

__parseClasses()

Private method to extract top-level classes.

Returns:: extracted class contexts (list of DocStyleContext)

DocStyleChecker.__parseContexts

__parseContexts(kind)

Private method to extract a context from the source.

kind: kind of context to extract (string)

Returns:: requested contexts (list of DocStyleContext)

DocStyleChecker.__parseDocstring

__parseDocstring(context, what='')

Private method to extract a docstring given `def` or `class` source.

context: context data to get the docstring from (DocStyleContext)
what: string denoting what is being parsed (string)

Returns:: context of extracted docstring (DocStyleContext)

DocStyleChecker.__parseFunctions

__parseFunctions()

Private method to extract top-level functions.

Returns:: extracted function contexts (list of DocStyleContext)

DocStyleChecker.__parseMethods

__parseMethods()

Private method to extract methods of all classes.

Returns:: extracted method contexts (list of DocStyleContext)

DocStyleChecker.__parseModuleDocstring

__parseModuleDocstring(source)

Private method to extract a docstring given a module source.

source: source to parse (list of string)

Returns:: context of extracted docstring (DocStyleContext)

DocStyleChecker.__parseTopLevel

__parseTopLevel(keyword)

Private method to extract top-level functions or classes.

keyword: keyword signaling what to extract (string)

Returns:: extracted function or class contexts (list of DocStyleContext)

DocStyleChecker.__readline

__readline()

Private method to get the next line from the source.

Returns:: next line of source (string)

DocStyleChecker.__reportInvalidSyntax

__reportInvalidSyntax()

Private method to report a syntax error.

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: token generator

Returns:: last token of the indented block

DocStyleChecker.run

run()

Public method to check the given source for violations of doc string conventions.

DocStyleChecker.unpackArgs

unpackArgs()

Local helper function to unpack function argument names.

args: list of AST node arguments

Returns:: list of argument names (list of string)

DocStyleContext

Class implementing the source context.

Derived from

object

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.
source	Public method to get the source.
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: source code of the context (list of string or string)
startLine: line number the context starts in the source (integer)
contextType: type of the context object (string)

DocStyleContext.contextType

contextType()

Public method to get the context type.

Returns:: context type (string)

DocStyleContext.end

end()

Public method to get the end line number.

Returns:: end line number (integer)

DocStyleContext.indent

indent()

Public method to get the indentation of the first line.

Returns:: indentation string (string)

DocStyleContext.source

source()

Public method to get the source.

Returns:: source (list of string)

DocStyleContext.ssource

ssource()

Public method to get the joined source lines.

Returns:: source (string)

DocStyleContext.start

start()

Public method to get the start line number.

Returns:: start line number (integer)