Preventing the D103 error when the function is decorated with @overload.

src/pydocstyle/checker.py

@@ -194,29 +194,6 @@ def check_docstring_missing(self, definition, docstring):
               with a single underscore.
 
         """
-        if (
-            not docstring
-            and definition.is_public
-            or docstring
-            and is_blank(ast.literal_eval(docstring))
-        ):
-            codes = {
-                Module: violations.D100,
-                Class: violations.D101,
-                NestedClass: violations.D106,
-                Method: (
-                    lambda: violations.D105()
-                    if definition.is_magic
-                    else (
-                        violations.D107()
-                        if definition.is_init
-                        else violations.D102()
-                    )
-                ),
-                Function: violations.D103,
-                NestedFunction: violations.D103,
-                Package: violations.D104,
-            }
         if (
             not docstring
             and definition.is_public
@@ -571,6 +548,18 @@ def check_capitalized(self, function, docstring):
             if first_word != first_word.capitalize():
                 return violations.D403(first_word.capitalize(), first_word)
 
+    @check_for(Function)
+    def check_if_needed(self, function, docstring):
+        """D418: Function decorated with @overload shouldn't contain a docstring.
+
+        Functions that are decorated with @overload are definitions,
+        and are for the benefit of the type checker only,
+        since they will be overwritten by the non-@overload-decorated definition.
+
+        """
+        if docstring and function.is_overload:
+            return violations.D418()
+
     @check_for(Definition)
     def check_starts_with_this(self, function, docstring):
         """D404: First word of the docstring should not be `This`.

src/pydocstyle/violations.py

@@ -411,6 +411,11 @@ def to_rst(cls) -> str:
     'argument(s) {0} are missing descriptions in {1!r} docstring',
 )
 
+D418 = D4xx.create_error(
+    'D418',
+    'Function decorated with @overload shouldn\'t contain a docstring',
+)
+
 
 class AttrDict(dict):
     def __getattr__(self, item: str) -> Any:
@@ -441,6 +446,7 @@ def __getattr__(self, item: str) -> Any:
             'D415',
             'D416',
             'D417',
+            'D418',
         },
         'numpy': all_errors
         - {

src/tests/test_cases/test.py

@@ -61,6 +61,8 @@ def overloaded_func(a: int) -> str:
 
 @overload
 def overloaded_func(a: str) -> str:
+    # TODO(Find a way to test D418
+    #  as @overload can't be passed to the @expect function)
     return '1'