# eric6.Plugins.CheckerPlugins.CodeStyleChecker.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

object

### 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.
__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.
__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 (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.

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
  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.__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
  docstring context (DocStyleContext)
context
  context of the docstring (DocStyleContext)

#### DocStyleChecker.__checkEricSummary

__checkEricSummary(docstringContext, context)

Private method to check, that method docstring summaries start with specific words.

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)

Up

## 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.
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
  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.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.

Returns:
  source (list of string)

#### DocStyleContext.special

special()

Public method to get the special context attribute string.

Returns:
  attribute string

Return Type:
  str

#### 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)

Up