issue9255 - Detect FIXME words in docstring #9281

You'll also need to add a documentation example. There is a CI check that sort of tells you what's wrong. Please let us know if you need more help figuring out what to do: that means we should update the error message of that CI step.

DanielNoord · 2023-12-05T08:12:47Z

pylint/checkers/base/docstring_checker.py

@@ -73,6 +73,11 @@ class DocStringChecker(_BasicChecker):
            "docstring.",
            {"old_names": [("C0111", "missing-docstring")]},
        ),
+        "C0150": (
+            "%s",


Could we make this message a little more descriptive? Something like:

Suggested change

"%s",

"Disallowed word in docstring: '%s'",

I know the original fixme message doesn't have this but I don't think that's nice 😄

DanielNoord · 2023-12-05T08:13:58Z

pylint/checkers/base/docstring_checker.py

+            fixme_words = self.linter.config.notes
+            for word in fixme_words:


Suggested change

fixme_words = self.linter.config.notes

for word in fixme_words:

for word in self.linter.config.notes:

DanielNoord · 2023-12-05T08:14:19Z

tests/functional/d/docstrings_fixme.py

+# pylint: disable=unnecessary-pass, consider-using-f-string
+
+"""
+Test fixme in docstrings.
+"""


Could you switch the comment and the docstring around?

DanielNoord · 2023-12-05T08:14:48Z

tests/functional/d/docstrings_fixme.py

+# fixme-in-docstring
+def func3(): # [fixme-in-docstring]
+    """
+    XXX: Implement


Could you add a test where the FIXME is not the first word of the line? And also one where it is not surrounded by spaces?

Pierre-Sassoulas

If it's a new check, we might want to disable it by default. Not sure it warrant to create a new message by the way. If we extends fixme then adding an option to raise on docstring (false by default) would be nice. What do you think @DanielNoord ?

Pierre-Sassoulas · 2023-12-05T08:17:21Z

pylint/checkers/base/docstring_checker.py

@@ -73,6 +73,11 @@ class DocStringChecker(_BasicChecker):
            "docstring.",
            {"old_names": [("C0111", "missing-docstring")]},
        ),
+        "C0150": (


I would expect this message to be in the same checker than fixme. Maybe even the same message.

Pierre-Sassoulas · 2023-12-05T08:19:33Z

pylint/checkers/base/docstring_checker.py

+        "C0150": (
+            "%s",
+            "fixme-in-docstring",
+            "Used when a warning note as FIXME or XXX is detected in docstring.",


Imo should be a rational (why it's bad) and not when it's raised. (I know the current descriptions are a bad example of that.)

DanielNoord · 2023-12-05T08:24:38Z

If it's a new check, we might want to disable it by default. Not sure it warrant to create a new message by the way. If we extends fixme then adding an option to raise on docstring (false by default) would be nice. What do you think @DanielNoord ?

I'm fine with adding it to fixme as well

shenjunjie2003 · 2023-12-06T16:06:01Z

Ok! Should I change to integrate it to fixme ?

Pierre-Sassoulas · 2023-12-06T20:25:21Z

Yes, I think pylint would be more consistent if it's still a fixme message but with a check-fixme-in-docstring option (default to false). Here's an example of options in a checker:

pylint/pylint/checkers/design_analysis.py

Lines 292 to 407 in 37081fd

    
               options = ( 
        
                   ( 
        
                       "max-args", 
        
                       { 
        
                           "default": 5, 
        
                           "type": "int", 
        
                           "metavar": "<int>", 
        
                           "help": "Maximum number of arguments for function / method.", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "max-locals", 
        
                       { 
        
                           "default": 15, 
        
                           "type": "int", 
        
                           "metavar": "<int>", 
        
                           "help": "Maximum number of locals for function / method body.", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "max-returns", 
        
                       { 
        
                           "default": 6, 
        
                           "type": "int", 
        
                           "metavar": "<int>", 
        
                           "help": "Maximum number of return / yield for function / " 
        
                           "method body.", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "max-branches", 
        
                       { 
        
                           "default": 12, 
        
                           "type": "int", 
        
                           "metavar": "<int>", 
        
                           "help": "Maximum number of branch for function / method body.", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "max-statements", 
        
                       { 
        
                           "default": 50, 
        
                           "type": "int", 
        
                           "metavar": "<int>", 
        
                           "help": "Maximum number of statements in function / method body.", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "max-parents", 
        
                       { 
        
                           "default": 7, 
        
                           "type": "int", 
        
                           "metavar": "<num>", 
        
                           "help": "Maximum number of parents for a class (see R0901).", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "ignored-parents", 
        
                       { 
        
                           "default": (), 
        
                           "type": "csv", 
        
                           "metavar": "<comma separated list of class names>", 
        
                           "help": "List of qualified class names to ignore when counting class parents (see R0901)", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "max-attributes", 
        
                       { 
        
                           "default": 7, 
        
                           "type": "int", 
        
                           "metavar": "<num>", 
        
                           "help": "Maximum number of attributes for a class \ 
        
           (see R0902).", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "min-public-methods", 
        
                       { 
        
                           "default": 2, 
        
                           "type": "int", 
        
                           "metavar": "<num>", 
        
                           "help": "Minimum number of public methods for a class \ 
        
           (see R0903).", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "max-public-methods", 
        
                       { 
        
                           "default": 20, 
        
                           "type": "int", 
        
                           "metavar": "<num>", 
        
                           "help": "Maximum number of public methods for a class \ 
        
           (see R0904).", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "max-bool-expr", 
        
                       { 
        
                           "default": 5, 
        
                           "type": "int", 
        
                           "metavar": "<num>", 
        
                           "help": "Maximum number of boolean expressions in an if " 
        
                           "statement (see R0916).", 
        
                       }, 
        
                   ), 
        
                   ( 
        
                       "exclude-too-few-public-methods", 
        
                       { 
        
                           "default": [], 
        
                           "type": "regexp_csv", 
        
                           "metavar": "<pattern>[,<pattern>...]", 
        
                           "help": "List of regular expressions of class ancestor names " 
        
                           "to ignore when counting public methods (see R0903)", 
        
                       }, 
        
                   ), 
        
               )

Jonny Shen and others added 2 commits December 4, 2023 16:32

issue9255 - Detect FIXME words in docstring

eacfdd0

[pre-commit.ci] auto fixes from pre-commit.com hooks

73d15fa

for more information, see https://pre-commit.ci

DanielNoord reviewed Dec 5, 2023

View reviewed changes

Pierre-Sassoulas reviewed Dec 5, 2023

View reviewed changes

jacobtylerwalls mentioned this pull request Dec 25, 2023

--ignore-patterns not working in primer config #9328

Closed

Pierre-Sassoulas added Enhancement ✨ Improvement to a component Waiting on author Indicate that maintainers are waiting for a message of the author labels Apr 29, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

issue9255 - Detect FIXME words in docstring #9281

issue9255 - Detect FIXME words in docstring #9281

shenjunjie2003 commented Dec 4, 2023

github-actions bot commented Dec 4, 2023

DanielNoord left a comment

DanielNoord Dec 5, 2023

DanielNoord Dec 5, 2023

DanielNoord Dec 5, 2023

DanielNoord Dec 5, 2023

Pierre-Sassoulas left a comment

Pierre-Sassoulas Dec 5, 2023 •

edited

Pierre-Sassoulas Dec 5, 2023

DanielNoord commented Dec 5, 2023

shenjunjie2003 commented Dec 6, 2023

Pierre-Sassoulas commented Dec 6, 2023

		fixme_words = self.linter.config.notes
		for word in fixme_words:

	fixme_words = self.linter.config.notes
	for word in fixme_words:
	for word in self.linter.config.notes:

issue9255 - Detect FIXME words in docstring #9281

Are you sure you want to change the base?

issue9255 - Detect FIXME words in docstring #9281

Conversation

shenjunjie2003 commented Dec 4, 2023

Type of Changes

Description

github-actions bot commented Dec 4, 2023

DanielNoord left a comment

Choose a reason for hiding this comment

DanielNoord Dec 5, 2023

Choose a reason for hiding this comment

DanielNoord Dec 5, 2023

Choose a reason for hiding this comment

DanielNoord Dec 5, 2023

Choose a reason for hiding this comment

DanielNoord Dec 5, 2023

Choose a reason for hiding this comment

Pierre-Sassoulas left a comment

Choose a reason for hiding this comment

Pierre-Sassoulas Dec 5, 2023 • edited

Choose a reason for hiding this comment

Pierre-Sassoulas Dec 5, 2023

Choose a reason for hiding this comment

DanielNoord commented Dec 5, 2023

shenjunjie2003 commented Dec 6, 2023

Pierre-Sassoulas commented Dec 6, 2023

Pierre-Sassoulas Dec 5, 2023 •

edited