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

src/pydocstyle/checker.py

@@ -213,8 +213,12 @@ def check_docstring_missing(self, definition, docstring):
                         else violations.D102()
                     )
                 ),
-                Function: violations.D103,
                 NestedFunction: violations.D103,
+                Function: (
+                    lambda: violations.D103()
+                    if not definition.is_overload
+                    else None
+                ),
                 Package: violations.D104,
             }
             return codes[type(definition)]()
@@ -544,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/parser.py

@@ -210,6 +210,14 @@ def is_public(self):
         else:
             return not self.name.startswith('_')
 
+    @property
+    def is_overload(self):
+        """Return True iff the method decorated with overload."""
+        for decorator in self.decorators:
+            if decorator.name == "overload":
+                return True
+        return False
+
     @property
     def is_test(self):
         """Return True if this function is a test function/method.

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

@@ -3,6 +3,7 @@
 import os
 import sys
 from .expected import Expectation
+from typing import overload
 
 
 expectation = Expectation()
@@ -53,6 +54,23 @@ def nested():
         ''
 
 
+@overload
+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)
+    ...
+
+
+def overloaded_func(a):
+    """Foo bar documentation."""
+    return str(a)
+
+
 @expect('D200: One-line docstring should fit on one line with quotes '
         '(found 3)')
 @expect('D212: Multi-line docstring summary should start at the first line')