From 81bcd668512899e48e316f3f91144b50fed58fa2 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 25 Sep 2018 20:04:41 +0200
Subject: [PATCH] Document inheriting docstrings

---
 doc/devel/documenting_mpl.rst | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
index 0ef18f7fde09..ecb86d53651e 100644
--- a/doc/devel/documenting_mpl.rst
+++ b/doc/devel/documenting_mpl.rst
@@ -632,6 +632,29 @@ definition.  There are some some manual hacks in this case, violating the
 "single entry point" requirement above -- see the ``docstring.interpd.update``
 calls in `matplotlib.patches`.
 
+
+Inheriting docstrings
+---------------------
+
+If a subclass overrides a method but does not change the semantics, we can
+reuse the parent docstring for the method of the child class. Python does this
+automatically, if the subclass method does not have a docstring.
+
+Use a plain comment `# docstring inherited` to denote the intention to reuse
+the parent docstring. That way we do not accidentially create a docstring in
+the future::
+
+    class A:
+        def foo():
+            """The parent docstring."""
+            pass
+
+    class B(A):
+        def foo():
+            # docstring inherited
+            pass
+
+
 .. _docstring-adding-figures:
 
 Adding figures