Skip to content

Commit

Permalink
[doc param checker] Add confidences for DocParam checker's message
Browse files Browse the repository at this point in the history
  • Loading branch information
@Pierre-Sassoulas
Pierre-Sassoulas committed Jul 21, 2022
1 parent dfb80a3 commit 2da790a
Show file tree
Hide file tree
Showing 28 changed files with 211 additions and 202 deletions.
21 changes: 15 additions & 6 deletions pylint/extensions/docparams.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
from pylint.checkers import utils as checker_utils
from pylint.extensions import _check_docs_utils as utils
from pylint.extensions._check_docs_utils import Docstring
from pylint.interfaces import HIGH

if TYPE_CHECKING:
from pylint.lint import PyLinter
Expand Down Expand Up @@ -259,7 +260,7 @@ def check_functiondef_returns(
if (node_doc.has_returns() or node_doc.has_rtype()) and not any(
utils.returns_something(ret_node) for ret_node in return_nodes
):
self.add_message("redundant-returns-doc", node=node)
self.add_message("redundant-returns-doc", node=node, confidence=HIGH)

def check_functiondef_yields(
self, node: nodes.FunctionDef, node_doc: Docstring
Expand Down Expand Up @@ -333,13 +334,13 @@ def visit_return(self, node: nodes.Return) -> None:
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)
self.add_message("missing-return-doc", node=func_node, confidence=HIGH)

if func_node.returns:
return

if not (doc.has_rtype() or (doc.has_property_type() and is_property)):
self.add_message("missing-return-type-doc", node=func_node)
self.add_message("missing-return-type-doc", node=func_node, confidence=HIGH)

def visit_yield(self, node: nodes.Yield | nodes.YieldFrom) -> None:
if self.linter.config.accept_no_yields_doc:
Expand All @@ -361,10 +362,10 @@ def visit_yield(self, node: nodes.Yield | nodes.YieldFrom) -> None:
doc_has_yields_type = doc.has_rtype()

if not doc_has_yields:
self.add_message("missing-yield-doc", node=func_node)
self.add_message("missing-yield-doc", node=func_node, confidence=HIGH)

if not (doc_has_yields_type or func_node.returns):
self.add_message("missing-yield-type-doc", node=func_node)
self.add_message("missing-yield-type-doc", node=func_node, confidence=HIGH)

visit_yieldfrom = visit_yield

Expand Down Expand Up @@ -405,6 +406,7 @@ def _compare_missing_args(
message_id,
args=(", ".join(sorted(missing_argument_names)),),
node=warning_node,
confidence=HIGH,
)

def _compare_different_args(
Expand Down Expand Up @@ -447,6 +449,7 @@ def _compare_different_args(
message_id,
args=(", ".join(sorted(differing_argument_names)),),
node=warning_node,
confidence=HIGH,
)

def _compare_ignored_args(
Expand Down Expand Up @@ -474,6 +477,7 @@ def _compare_ignored_args(
message_id,
args=(", ".join(sorted(existing_ignored_argument_names)),),
node=warning_node,
confidence=HIGH,
)

def check_arguments_in_docstring(
Expand Down Expand Up @@ -582,6 +586,7 @@ class constructor.
"missing-any-param-doc",
args=(warning_node.name,),
node=warning_node,
confidence=HIGH,
)
else:
self._compare_missing_args(
Expand Down Expand Up @@ -626,7 +631,10 @@ def check_single_constructor_params(
) -> None:
if class_doc.has_params() and init_doc.has_params():
self.add_message(
"multiple-constructor-doc", args=(class_node.name,), node=class_node
"multiple-constructor-doc",
args=(class_node.name,),
node=class_node,
confidence=HIGH,
)

def _handle_no_raise_doc(self, excs: set[str], node: nodes.FunctionDef) -> None:
Expand All @@ -653,6 +661,7 @@ def _add_raise_message(
"missing-raises-doc",
args=(", ".join(sorted(missing_exceptions)),),
node=node,
confidence=HIGH,
)


Expand Down
32 changes: 16 additions & 16 deletions tests/functional/ext/docparams/docparams.txt
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
missing-return-doc:4:0:4:18:_private_func1:Missing return documentation:UNDEFINED
missing-return-type-doc:4:0:4:18:_private_func1:Missing return type documentation:UNDEFINED
missing-yield-doc:9:0:9:18:_private_func2:Missing yield documentation:UNDEFINED
missing-yield-type-doc:9:0:9:18:_private_func2:Missing yield type documentation:UNDEFINED
missing-raises-doc:14:0:14:18:_private_func3:"""Exception"" not documented as being raised":UNDEFINED
missing-any-param-doc:19:0:19:16:public_func1:"Missing any documentation in ""public_func1""":UNDEFINED
missing-return-doc:24:0:24:30:_async_private_func1:Missing return documentation:UNDEFINED
missing-return-type-doc:24:0:24:30:_async_private_func1:Missing return type documentation:UNDEFINED
missing-yield-doc:29:0:29:30:_async_private_func2:Missing yield documentation:UNDEFINED
missing-yield-type-doc:29:0:29:30:_async_private_func2:Missing yield type documentation:UNDEFINED
missing-raises-doc:34:0:34:30:_async_private_func3:"""Exception"" not documented as being raised":UNDEFINED
missing-any-param-doc:39:0:39:28:async_public_func1:"Missing any documentation in ""async_public_func1""":UNDEFINED
differing-param-doc:44:0:44:23:differing_param_doc:"""param"" differing in parameter documentation":UNDEFINED
differing-param-doc:55:0:55:35:differing_param_doc_kwords_only:"""param"" differing in parameter documentation":UNDEFINED
missing-type-doc:66:0:66:20:missing_type_doc:"""par1"" missing in parameter type documentation":UNDEFINED
missing-type-doc:76:0:76:32:missing_type_doc_kwords_only:"""par1"" missing in parameter type documentation":UNDEFINED
missing-return-doc:4:0:4:18:_private_func1:Missing return documentation:HIGH
missing-return-type-doc:4:0:4:18:_private_func1:Missing return type documentation:HIGH
missing-yield-doc:9:0:9:18:_private_func2:Missing yield documentation:HIGH
missing-yield-type-doc:9:0:9:18:_private_func2:Missing yield type documentation:HIGH
missing-raises-doc:14:0:14:18:_private_func3:"""Exception"" not documented as being raised":HIGH
missing-any-param-doc:19:0:19:16:public_func1:"Missing any documentation in ""public_func1""":HIGH
missing-return-doc:24:0:24:30:_async_private_func1:Missing return documentation:HIGH
missing-return-type-doc:24:0:24:30:_async_private_func1:Missing return type documentation:HIGH
missing-yield-doc:29:0:29:30:_async_private_func2:Missing yield documentation:HIGH
missing-yield-type-doc:29:0:29:30:_async_private_func2:Missing yield type documentation:HIGH
missing-raises-doc:34:0:34:30:_async_private_func3:"""Exception"" not documented as being raised":HIGH
missing-any-param-doc:39:0:39:28:async_public_func1:"Missing any documentation in ""async_public_func1""":HIGH
differing-param-doc:44:0:44:23:differing_param_doc:"""param"" differing in parameter documentation":HIGH
differing-param-doc:55:0:55:35:differing_param_doc_kwords_only:"""param"" differing in parameter documentation":HIGH
missing-type-doc:66:0:66:20:missing_type_doc:"""par1"" missing in parameter type documentation":HIGH
missing-type-doc:76:0:76:32:missing_type_doc_kwords_only:"""par1"" missing in parameter type documentation":HIGH
4 changes: 2 additions & 2 deletions tests/functional/ext/docparams/docparams_py38.txt
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
differing-param-doc:4:0:4:32:differing_param_doc_pos_only:"""param"" differing in parameter documentation":UNDEFINED
missing-type-doc:15:0:15:29:missing_type_doc_pos_only:"""par1"" missing in parameter type documentation":UNDEFINED
differing-param-doc:4:0:4:32:differing_param_doc_pos_only:"""param"" differing in parameter documentation":HIGH
missing-type-doc:15:0:15:29:missing_type_doc_pos_only:"""par1"" missing in parameter type documentation":HIGH
36 changes: 18 additions & 18 deletions tests/functional/ext/docparams/missing_param_doc.txt
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
missing-any-param-doc:3:0:3:11:foobar1:"Missing any documentation in ""foobar1""":UNDEFINED
missing-any-param-doc:8:0:8:11:foobar2:"Missing any documentation in ""foobar2""":UNDEFINED
missing-param-doc:15:0:15:11:foobar3:"""arg1, arg2, arg3"" missing in parameter documentation":UNDEFINED
missing-type-doc:15:0:15:11:foobar3:"""arg2"" missing in parameter type documentation":UNDEFINED
missing-param-doc:24:0:24:11:foobar4:"""arg2"" missing in parameter documentation":UNDEFINED
missing-type-doc:24:0:24:11:foobar4:"""arg2"" missing in parameter type documentation":UNDEFINED
missing-param-doc:33:0:33:11:foobar5:"""arg2"" missing in parameter documentation":UNDEFINED
missing-type-doc:33:0:33:11:foobar5:"""arg1"" missing in parameter type documentation":UNDEFINED
missing-param-doc:43:0:43:11:foobar6:"""arg2, arg3"" missing in parameter documentation":UNDEFINED
missing-type-doc:43:0:43:11:foobar6:"""arg3"" missing in parameter type documentation":UNDEFINED
missing-any-param-doc:53:0:53:11:foobar7:"Missing any documentation in ""foobar7""":UNDEFINED
missing-any-param-doc:61:0:61:11:foobar8:"Missing any documentation in ""foobar8""":UNDEFINED
missing-param-doc:66:0:66:11:foobar9:"""arg1, arg2, arg3"" missing in parameter documentation":UNDEFINED
missing-param-doc:76:0:76:12:foobar10:"""arg2"" missing in parameter documentation":UNDEFINED
missing-type-doc:76:0:76:12:foobar10:"""arg1, arg3"" missing in parameter type documentation":UNDEFINED
missing-any-param-doc:88:0:88:12:foobar11:"Missing any documentation in ""foobar11""":UNDEFINED
missing-param-doc:97:0:97:12:foobar12:"""arg1, arg3"" missing in parameter documentation":UNDEFINED
missing-type-doc:97:0:97:12:foobar12:"""arg2, arg3"" missing in parameter type documentation":UNDEFINED
missing-any-param-doc:3:0:3:11:foobar1:"Missing any documentation in ""foobar1""":HIGH
missing-any-param-doc:8:0:8:11:foobar2:"Missing any documentation in ""foobar2""":HIGH
missing-param-doc:15:0:15:11:foobar3:"""arg1, arg2, arg3"" missing in parameter documentation":HIGH
missing-type-doc:15:0:15:11:foobar3:"""arg2"" missing in parameter type documentation":HIGH
missing-param-doc:24:0:24:11:foobar4:"""arg2"" missing in parameter documentation":HIGH
missing-type-doc:24:0:24:11:foobar4:"""arg2"" missing in parameter type documentation":HIGH
missing-param-doc:33:0:33:11:foobar5:"""arg2"" missing in parameter documentation":HIGH
missing-type-doc:33:0:33:11:foobar5:"""arg1"" missing in parameter type documentation":HIGH
missing-param-doc:43:0:43:11:foobar6:"""arg2, arg3"" missing in parameter documentation":HIGH
missing-type-doc:43:0:43:11:foobar6:"""arg3"" missing in parameter type documentation":HIGH
missing-any-param-doc:53:0:53:11:foobar7:"Missing any documentation in ""foobar7""":HIGH
missing-any-param-doc:61:0:61:11:foobar8:"Missing any documentation in ""foobar8""":HIGH
missing-param-doc:66:0:66:11:foobar9:"""arg1, arg2, arg3"" missing in parameter documentation":HIGH
missing-param-doc:76:0:76:12:foobar10:"""arg2"" missing in parameter documentation":HIGH
missing-type-doc:76:0:76:12:foobar10:"""arg1, arg3"" missing in parameter type documentation":HIGH
missing-any-param-doc:88:0:88:12:foobar11:"Missing any documentation in ""foobar11""":HIGH
missing-param-doc:97:0:97:12:foobar12:"""arg1, arg3"" missing in parameter documentation":HIGH
missing-type-doc:97:0:97:12:foobar12:"""arg2, arg3"" missing in parameter type documentation":HIGH
6 changes: 3 additions & 3 deletions tests/functional/ext/docparams/parameter/missing_param_doc_required.txt
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
missing-any-param-doc:7:0:7:53:test_don_t_tolerate_no_param_documentation_at_all:"Missing any documentation in ""test_don_t_tolerate_no_param_documentation_at_all""":UNDEFINED
missing-param-doc:44:0:44:40:test_kwonlyargs_are_taken_in_account:"""missing_kwonly"" missing in parameter documentation":UNDEFINED
missing-type-doc:44:0:44:40:test_kwonlyargs_are_taken_in_account:"""missing_kwonly"" missing in parameter type documentation":UNDEFINED
missing-any-param-doc:7:0:7:53:test_don_t_tolerate_no_param_documentation_at_all:"Missing any documentation in ""test_don_t_tolerate_no_param_documentation_at_all""":HIGH
missing-param-doc:44:0:44:40:test_kwonlyargs_are_taken_in_account:"""missing_kwonly"" missing in parameter documentation":HIGH
missing-type-doc:44:0:44:40:test_kwonlyargs_are_taken_in_account:"""missing_kwonly"" missing in parameter type documentation":HIGH
52 changes: 26 additions & 26 deletions tests/functional/ext/docparams/parameter/missing_param_doc_required_Google.txt
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
missing-param-doc:24:0:24:48:test_missing_func_params_in_google_docstring:"""y"" missing in parameter documentation":UNDEFINED
missing-type-doc:24:0:24:48:test_missing_func_params_in_google_docstring:"""x, y"" missing in parameter type documentation":UNDEFINED
missing-type-doc:80:0:80:73:test_missing_func_params_with_partial_annotations_in_google_docstring:"""x"" missing in parameter type documentation":UNDEFINED
differing-param-doc:131:0:131:65:test_func_params_and_wrong_keyword_params_in_google_docstring:"""these"" differing in parameter documentation":UNDEFINED
differing-type-doc:131:0:131:65:test_func_params_and_wrong_keyword_params_in_google_docstring:"""these"" differing in parameter type documentation":UNDEFINED
missing-param-doc:131:0:131:65:test_func_params_and_wrong_keyword_params_in_google_docstring:"""that"" missing in parameter documentation":UNDEFINED
missing-type-doc:131:0:131:65:test_func_params_and_wrong_keyword_params_in_google_docstring:"""that"" missing in parameter type documentation":UNDEFINED
missing-param-doc:148:4:148:54:Foo.test_missing_method_params_in_google_docstring:"""y"" missing in parameter documentation":UNDEFINED
missing-type-doc:148:4:148:54:Foo.test_missing_method_params_in_google_docstring:"""x, y"" missing in parameter type documentation":UNDEFINED
differing-param-doc:179:0:179:58:test_wrong_name_of_func_params_in_google_docstring_one:"""xarg1, zarg1"" differing in parameter documentation":UNDEFINED
differing-type-doc:179:0:179:58:test_wrong_name_of_func_params_in_google_docstring_one:"""xarg1, zarg1"" differing in parameter type documentation":UNDEFINED
missing-param-doc:179:0:179:58:test_wrong_name_of_func_params_in_google_docstring_one:"""xarg, zarg"" missing in parameter documentation":UNDEFINED
missing-type-doc:179:0:179:58:test_wrong_name_of_func_params_in_google_docstring_one:"""xarg, zarg"" missing in parameter type documentation":UNDEFINED
differing-param-doc:194:0:194:58:test_wrong_name_of_func_params_in_google_docstring_two:"""yarg1"" differing in parameter documentation":UNDEFINED
differing-type-doc:194:0:194:58:test_wrong_name_of_func_params_in_google_docstring_two:"""yarg1"" differing in parameter type documentation":UNDEFINED
missing-param-doc:221:0:221:14:ClassFoo:"""x"" missing in parameter documentation":UNDEFINED
missing-type-doc:221:0:221:14:ClassFoo:"""x, y"" missing in parameter type documentation":UNDEFINED
missing-param-doc:239:4:239:16:ClassFoo.__init__:"""x"" missing in parameter documentation":UNDEFINED
missing-type-doc:239:4:239:16:ClassFoo.__init__:"""x, y"" missing in parameter type documentation":UNDEFINED
missing-param-doc:251:0:251:14:ClassFoo:"""x"" missing in parameter documentation":UNDEFINED
missing-type-doc:251:0:251:14:ClassFoo:"""x, y"" missing in parameter type documentation":UNDEFINED
multiple-constructor-doc:251:0:251:14:ClassFoo:"""ClassFoo"" has constructor parameters documented in class and __init__":UNDEFINED
missing-param-doc:265:4:265:16:ClassFoo.__init__:"""x"" missing in parameter documentation":UNDEFINED
missing-type-doc:265:4:265:16:ClassFoo.__init__:"""x, y"" missing in parameter type documentation":UNDEFINED
missing-param-doc:275:0:275:34:test_warns_missing_args_google:"""*args"" missing in parameter documentation":UNDEFINED
missing-param-doc:288:0:288:36:test_warns_missing_kwargs_google:"""**kwargs"" missing in parameter documentation":UNDEFINED
missing-param-doc:24:0:24:48:test_missing_func_params_in_google_docstring:"""y"" missing in parameter documentation":HIGH
missing-type-doc:24:0:24:48:test_missing_func_params_in_google_docstring:"""x, y"" missing in parameter type documentation":HIGH
missing-type-doc:80:0:80:73:test_missing_func_params_with_partial_annotations_in_google_docstring:"""x"" missing in parameter type documentation":HIGH
differing-param-doc:131:0:131:65:test_func_params_and_wrong_keyword_params_in_google_docstring:"""these"" differing in parameter documentation":HIGH
differing-type-doc:131:0:131:65:test_func_params_and_wrong_keyword_params_in_google_docstring:"""these"" differing in parameter type documentation":HIGH
missing-param-doc:131:0:131:65:test_func_params_and_wrong_keyword_params_in_google_docstring:"""that"" missing in parameter documentation":HIGH
missing-type-doc:131:0:131:65:test_func_params_and_wrong_keyword_params_in_google_docstring:"""that"" missing in parameter type documentation":HIGH
missing-param-doc:148:4:148:54:Foo.test_missing_method_params_in_google_docstring:"""y"" missing in parameter documentation":HIGH
missing-type-doc:148:4:148:54:Foo.test_missing_method_params_in_google_docstring:"""x, y"" missing in parameter type documentation":HIGH
differing-param-doc:179:0:179:58:test_wrong_name_of_func_params_in_google_docstring_one:"""xarg1, zarg1"" differing in parameter documentation":HIGH
differing-type-doc:179:0:179:58:test_wrong_name_of_func_params_in_google_docstring_one:"""xarg1, zarg1"" differing in parameter type documentation":HIGH
missing-param-doc:179:0:179:58:test_wrong_name_of_func_params_in_google_docstring_one:"""xarg, zarg"" missing in parameter documentation":HIGH
missing-type-doc:179:0:179:58:test_wrong_name_of_func_params_in_google_docstring_one:"""xarg, zarg"" missing in parameter type documentation":HIGH
differing-param-doc:194:0:194:58:test_wrong_name_of_func_params_in_google_docstring_two:"""yarg1"" differing in parameter documentation":HIGH
differing-type-doc:194:0:194:58:test_wrong_name_of_func_params_in_google_docstring_two:"""yarg1"" differing in parameter type documentation":HIGH
missing-param-doc:221:0:221:14:ClassFoo:"""x"" missing in parameter documentation":HIGH
missing-type-doc:221:0:221:14:ClassFoo:"""x, y"" missing in parameter type documentation":HIGH
missing-param-doc:239:4:239:16:ClassFoo.__init__:"""x"" missing in parameter documentation":HIGH
missing-type-doc:239:4:239:16:ClassFoo.__init__:"""x, y"" missing in parameter type documentation":HIGH
missing-param-doc:251:0:251:14:ClassFoo:"""x"" missing in parameter documentation":HIGH
missing-type-doc:251:0:251:14:ClassFoo:"""x, y"" missing in parameter type documentation":HIGH
multiple-constructor-doc:251:0:251:14:ClassFoo:"""ClassFoo"" has constructor parameters documented in class and __init__":HIGH
missing-param-doc:265:4:265:16:ClassFoo.__init__:"""x"" missing in parameter documentation":HIGH
missing-type-doc:265:4:265:16:ClassFoo.__init__:"""x, y"" missing in parameter type documentation":HIGH
missing-param-doc:275:0:275:34:test_warns_missing_args_google:"""*args"" missing in parameter documentation":HIGH
missing-param-doc:288:0:288:36:test_warns_missing_kwargs_google:"""**kwargs"" missing in parameter documentation":HIGH
Loading

0 comments on commit 2da790a

Please sign in to comment.