[missing-docstring] Break down into class, function, and module

Also fixed spelling in C0112 to C0116 messages following the review
of pull-request #2036 by Ashley Whetter.

See also #2075, #2077, #2262, #2654, #2805, #2809, #2844, #2992
and #3013 for full historical context.

CONTRIBUTORS.txt

@@ -136,6 +136,9 @@ contributors:
 
 * Erik Eriksson - Added overlapping-except error check.
 
+* Pierre Sassoulas : Broke down "missing-docstrings" between "module", "class"
+  and "function", made multiple message with the same old name possible.
+
 * Anthony Foglia (Google): Added simple string slots check.
 
 * Derek Gustafson: contributor

ChangeLog

@@ -1080,6 +1080,13 @@ Release date: 2018-07-15
 
       Close 1992
 
+    * Broke down "missing-docstrings" between "module", "class" and "function"
+
+      For this to work we had to make multiple messages with the same old name
+      possible.
+
+      Closes #1164
+
 What's New in Pylint 1.9?
 =========================
 

pylint/checkers/base.py

@@ -1942,19 +1942,34 @@ def _name_became_keyword_in_version(name, rules):
 
 class DocStringChecker(_BasicChecker):
     msgs = {
-        "C0111": (
-            "Missing %s docstring",  # W0131
-            "missing-docstring",
-            "Used when a module, function, class or method has no docstring. "
-            "Some special methods like __init__ don't necessarily require a "
-            "docstring.",
-        ),
         "C0112": (
             "Empty %s docstring",  # W0132
             "empty-docstring",
             "Used when a module, function, class or method has an empty "
             "docstring (it would be too easy ;).",
         ),
+        "C0114": (
+            "Missing module docstring",
+            "missing-module-docstring",
+            "Used when a module has no docstring."
+            "Empty modules do not require a docstring.",
+            {"old_names": [("C0111", "missing-docstring")]},
+        ),
+        "C0115": (
+            "Missing class docstring",
+            "missing-class-docstring",
+            "Used when a class has no docstring."
+            "Even an empty class must have a docstring.",
+            {"old_names": [("C0111", "missing-docstring")]},
+        ),
+        "C0116": (
+            "Missing function or method docstring",
+            "missing-function-docstring",
+            "Used when a function or method has no docstring."
+            "Some special methods like __init__ do not require a "
+            "docstring.",
+            {"old_names": [("C0111", "missing-docstring")]},
+        ),
     }
     options = (
         (
@@ -2064,9 +2079,13 @@ def _check_docstring(
                         return
                     if func.bound.name in ("str", "unicode", "bytes"):
                         return
-            self.add_message(
-                "missing-docstring", node=node, args=(node_type,), confidence=confidence
-            )
+            if node_type == "module":
+                message = "missing-module-docstring"
+            elif node_type == "class":
+                message = "missing-class-docstring"
+            else:
+                message = "missing-function-docstring"
+            self.add_message(message, node=node, confidence=confidence)
         elif not docstring.strip():
             self.stats["undocumented_" + node_type] += 1
             self.add_message(

tests/functional/d/docstrings.py

@@ -1,12 +1,12 @@
 # pylint: disable=R0201, useless-object-inheritance, unnecessary-pass
-# -1: [missing-docstring]
+# -1: [missing-module-docstring]
 from __future__ import print_function
 
 # +1: [empty-docstring]
 def function0():
     """"""
 
-# +1: [missing-docstring]
+# +1: [missing-function-docstring]
 def function1(value):
     # missing docstring
     print(value)
@@ -19,7 +19,7 @@ def function3(value):
     """docstring"""
     print(value)
 
-# +1: [missing-docstring]
+# +1: [missing-class-docstring]
 class AAAA(object):
     # missing docstring
 
@@ -36,7 +36,7 @@ class AAAA(object):
 ##             """ yeah !"""
 ##             pass
 
-    # +1: [missing-docstring]
+    # +1: [missing-function-docstring]
     def method1(self):
         pass
 
@@ -66,7 +66,7 @@ def method2(self):
     def method3(self):
         pass
 
-    # +1: [missing-docstring]
+    # +1: [missing-function-docstring]
     def method4(self):
         pass
 

tests/functional/d/docstrings.txt

@@ -1,8 +1,8 @@
-missing-docstring:1::Missing module docstring
+missing-module-docstring:1::Missing module docstring
 empty-docstring:6:function0:Empty function docstring
-missing-docstring:10:function1:Missing function docstring
-missing-docstring:23:AAAA:Missing class docstring
-missing-docstring:40:AAAA.method1:Missing method docstring:INFERENCE
+missing-function-docstring:10:function1:Missing function or method docstring
+missing-class-docstring:23:AAAA:Missing class docstring
+missing-function-docstring:40:AAAA.method1:Missing function or method docstring:INFERENCE
 empty-docstring:48:AAAA.method3:Empty method docstring:INFERENCE
 empty-docstring:62:DDDD.method2:Empty method docstring:INFERENCE
-missing-docstring:70:DDDD.method4:Missing method docstring:INFERENCE
+missing-function-docstring:70:DDDD.method4:Missing function or method docstring:INFERENCE

tests/functional/m/messages_managed_by_id.py

@@ -6,6 +6,6 @@ def foo(): #pylint: disable=C0102
 def toto(): #pylint: disable=C0102,R1711
     return
 
-# +1: [missing-docstring]
+# +1: [missing-function-docstring]
 def test_enabled_by_id_msg(): #pylint: enable=C0111
     pass

tests/functional/m/messages_managed_by_id.txt

@@ -3,4 +3,4 @@ use-symbolic-message-instead:3::"Id 'C0102' is used to disable 'blacklisted-name
 use-symbolic-message-instead:6::"Id 'C0102' is used to disable 'blacklisted-name' message emission"
 use-symbolic-message-instead:6::"Id 'R1711' is used to disable 'useless-return' message emission"
 use-symbolic-message-instead:10::"Id 'C0111' is used to enable 'missing-docstring' message emission"
-missing-docstring:10:test_enabled_by_id_msg:"Missing function docstring"
+missing-function-docstring:10:test_enabled_by_id_msg:"Missing function or method docstring"

tests/functional/m/missing_docstring.py

@@ -1,4 +1,4 @@
-# [missing-docstring]
+# [missing-module-docstring]
 # pylint: disable=too-few-public-methods, useless-object-inheritance
 
 def public_documented():
@@ -18,11 +18,11 @@ class ClassDocumented(object):
     """It has a docstring."""
 
 
-class ClassUndocumented(object): # [missing-docstring]
+class ClassUndocumented(object): # [missing-class-docstring]
     pass
 
 
-def public_undocumented(): # [missing-docstring]
+def public_undocumented(): # [missing-function-docstring]
     pass
 
 

tests/functional/m/missing_docstring.txt

@@ -1,3 +1,3 @@
-missing-docstring:1::Missing module docstring
-missing-docstring:21:ClassUndocumented:Missing class docstring
-missing-docstring:25:public_undocumented:Missing function docstring
+missing-module-docstring:1::Missing module docstring
+missing-class-docstring:21:ClassUndocumented:Missing class docstring
+missing-function-docstring:25:public_undocumented:Missing function or method docstring

tests/test_self.py

@@ -344,8 +344,8 @@ def test_enable_all_works(self):
             """
         ************* Module data.clientmodule_test
         {0}:10:8: W0612: Unused variable 'local_variable' (unused-variable)
-        {0}:18:4: C0111: Missing method docstring (missing-docstring)
-        {0}:22:0: C0111: Missing class docstring (missing-docstring)
+        {0}:18:4: C0116: Missing function or method docstring (missing-function-docstring)
+        {0}:22:0: C0115: Missing class docstring (missing-class-docstring)
         """.format(
                 module
             )
@@ -542,8 +542,8 @@ def test_pylintrc_comments_in_values(self):
             """
         ************* Module test_pylintrc_comments
         {0}:2:0: W0311: Bad indentation. Found 1 spaces, expected 4 (bad-indentation)
-        {0}:1:0: C0111: Missing module docstring (missing-docstring)
-        {0}:1:0: C0111: Missing function docstring (missing-docstring)
+        {0}:1:0: C0114: Missing module docstring (missing-module-docstring)
+        {0}:1:0: C0116: Missing function or method docstring (missing-function-docstring)
         """.format(
                 path
             )

tests/unittest_checker_base.py

@@ -32,7 +32,7 @@ class TestDocstring(CheckerTestCase):
 
     def test_missing_docstring_module(self):
         module = astroid.parse("something")
-        message = Message("missing-docstring", node=module, args=("module",))
+        message = Message("missing-module-docstring", node=module)
         with self.assertAddsMessages(message):
             self.checker.visit_module(module)
 
@@ -53,7 +53,7 @@ def test_empty_docstring_function(self):
         def func(tion):
            pass"""
         )
-        message = Message("missing-docstring", node=func, args=("function",))
+        message = Message("missing-function-docstring", node=func)
         with self.assertAddsMessages(message):
             self.checker.visit_functiondef(func)
 
@@ -76,7 +76,7 @@ def func(tion):
             pass
            """
         )
-        message = Message("missing-docstring", node=func, args=("function",))
+        message = Message("missing-function-docstring", node=func)
         with self.assertAddsMessages(message):
             self.checker.visit_functiondef(func)
 
@@ -91,7 +91,7 @@ def func(tion):
                 pass
            """
         )
-        message = Message("missing-docstring", node=func, args=("function",))
+        message = Message("missing-function-docstring", node=func)
         with self.assertAddsMessages(message):
             self.checker.visit_functiondef(func)
 
@@ -111,7 +111,7 @@ def test_class_no_docstring(self):
         class Klass(object):
            pass"""
         )
-        message = Message("missing-docstring", node=klass, args=("class",))
+        message = Message("missing-class-docstring", node=klass)
         with self.assertAddsMessages(message):
             self.checker.visit_classdef(klass)