def visit_yield(self, node):
"""Visits a function node that contains a yield statement and verifies
that the yield value and the yield type are documented.
Args:
node: astroid.scoped_nodes.Function. Node for a function or
method definition in the AST.
"""
func_node = node.frame()
if not isinstance(func_node, astroid.FunctionDef):
return
doc = docstrings_checker.docstringify(func_node.doc)
if not doc.is_valid() and self.config.accept_no_yields_doc:
return
if doc.supports_yields:
doc_has_yields = doc.has_yields()
doc_has_yields_type = doc.has_yields_type()
else:
doc_has_yields = doc.has_returns()
doc_has_yields_type = doc.has_rtype()
if not doc_has_yields:
self.add_message('missing-yield-doc', node=func_node)
if not doc_has_yields_type:
self.add_message('missing-yield-type-doc', node=func_node)
def visit_raise(self, node):
func_node = node.frame()
if not isinstance(func_node, astroid.FunctionDef):
return
expected_excs = docstrings_checker.possible_exc_types(node)
if not expected_excs:
return
if not func_node.doc:
# If this is a property setter,
# the property should have the docstring instead.
property_ = docstrings_checker.get_setters_property(func_node)
if property_:
func_node = property_
doc = docstrings_checker.docstringify(func_node.doc)
if not doc.is_valid():
if doc.doc:
self._handle_no_raise_doc(expected_excs, func_node)
return
found_excs = doc.exceptions()
missing_excs = expected_excs - found_excs
self._add_raise_message(missing_excs, func_node)
def visit_return(self, node):
"""Visits a function node that contains a return statement and verifies
that the return value and the return type are documented.
Args:
node: astroid.scoped_nodes.Function. Node for a function or
method definition in the AST.
"""
if not docstrings_checker.returns_something(node):
return
func_node = node.frame()
if not isinstance(func_node, astroid.FunctionDef):
return
doc = docstrings_checker.docstringify(func_node.doc)
if not doc.is_valid() and self.config.accept_no_return_doc:
return
is_property = checker_utils.decorated_with_property(func_node)
if not (doc.has_returns() or
(doc.has_property_returns() and is_property)):
self.add_message('missing-return-doc', node=func_node)
if not (doc.has_rtype() or (doc.has_property_type() and is_property)):
self.add_message('missing-return-type-doc', node=func_node)
def visit_raise(self, node):
"""Visits a function node that raises an exception and verifies that all
exceptions raised in the function definition are documented.
Args:
node: astroid.scoped_nodes.Function. Node for a function or
method definition in the AST.
"""
func_node = node.frame()
if not isinstance(func_node, astroid.FunctionDef):
return
expected_excs = docstrings_checker.possible_exc_types(node)
if not expected_excs:
return
if not func_node.doc:
# If this is a property setter,
# the property should have the docstring instead.
property_ = docstrings_checker.get_setters_property(func_node)
if property_:
func_node = property_
doc = docstrings_checker.docstringify(func_node.doc)
if not doc.is_valid():
if doc.doc:
self._handle_no_raise_doc(expected_excs, func_node)
return
found_excs = doc.exceptions()
missing_excs = expected_excs - found_excs
self._add_raise_message(missing_excs, func_node)
def check_functiondef_params(self, node, node_doc):
"""Checks whether all parameters in a function definition are
documented.
Args:
node: astroid.scoped_nodes.Function. Node for a function or
method definition in the AST.
node_doc: Docstring. Pylint Docstring class instance representing
a node's docstring.
"""
node_allow_no_param = None
if node.name in self.constructor_names:
class_node = checker_utils.node_frame_class(node)
if class_node is not None:
class_doc = docstrings_checker.docstringify(class_node.doc)
self.check_single_constructor_params(class_doc, node_doc,
class_node)
# __init__ or class docstrings can have no parameters documented
# as long as the other documents them.
node_allow_no_param = (class_doc.has_params() or
class_doc.params_documented_elsewhere()
or None)
class_allow_no_param = (node_doc.has_params() or
node_doc.params_documented_elsewhere()
or None)
self.check_arguments_in_docstring(
class_doc,
node.args,
class_node,
accept_no_param_doc=class_allow_no_param)
self.check_arguments_in_docstring(
node_doc, node.args, node, accept_no_param_doc=node_allow_no_param)
def visit_functiondef(self, node):
"""Called for function and method definitions (def).
Args:
node: astroid.scoped_nodes.Function. Node for a function or
method definition in the AST.
"""
node_doc = docstrings_checker.docstringify(node.doc)
self.check_functiondef_params(node, node_doc)
self.check_functiondef_returns(node, node_doc)
self.check_functiondef_yields(node, node_doc)
def visit_return(self, node):
if not docstrings_checker.returns_something(node):
return
func_node = node.frame()
if not isinstance(func_node, astroid.FunctionDef):
return
doc = docstrings_checker.docstringify(func_node.doc)
if not doc.is_valid() and self.config.accept_no_return_doc:
return
is_property = checker_utils.decorated_with_property(func_node)
if not (doc.has_returns() or
(doc.has_property_returns() and is_property)):
self.add_message('missing-return-doc', node=func_node)
if not (doc.has_rtype() or (doc.has_property_type() and is_property)):
self.add_message('missing-return-type-doc', node=func_node)
def visit_yield(self, node):
func_node = node.frame()
if not isinstance(func_node, astroid.FunctionDef):
return
doc = docstrings_checker.docstringify(func_node.doc)
if not doc.is_valid() and self.config.accept_no_yields_doc:
return
if doc.supports_yields:
doc_has_yields = doc.has_yields()
doc_has_yields_type = doc.has_yields_type()
else:
doc_has_yields = doc.has_returns()
doc_has_yields_type = doc.has_rtype()
if not doc_has_yields:
self.add_message('missing-yield-doc', node=func_node)
if not doc_has_yields_type:
self.add_message('missing-yield-type-doc', node=func_node)
def check_functiondef_params(self, node, node_doc):
node_allow_no_param = None
if node.name in self.constructor_names:
class_node = checker_utils.node_frame_class(node)
if class_node is not None:
class_doc = docstrings_checker.docstringify(class_node.doc)
self.check_single_constructor_params(class_doc, node_doc,
class_node)
# __init__ or class docstrings can have no parameters documented
# as long as the other documents them.
node_allow_no_param = (class_doc.has_params() or
class_doc.params_documented_elsewhere()
or None)
class_allow_no_param = (node_doc.has_params() or
node_doc.params_documented_elsewhere()
or None)
self.check_arguments_in_docstring(class_doc, node.args,
class_node,
class_allow_no_param)
self.check_arguments_in_docstring(node_doc, node.args, node,
node_allow_no_param)
