Add doc example for various messages (#7684)

* add docs for non-str-assignment

* add docs for nonlocal

* add docs for not-a-mapping

* add docs for possibly unused var

* add docs for preferred module

* add docs for redundant return doc

20 files changed, 62 insertions, 12 deletions

diff --git a/doc/data/messages/n/non-str-assignment-to-dunder-name/bad.py b/doc/data/messages/n/non-str-assignment-to-dunder-name/bad.py
new file mode 100644
index 000000000..59f13a13c
--- /dev/null
+++ b/doc/data/messages/n/non-str-assignment-to-dunder-name/bad.py
@@ -0,0 +1,5 @@
+class Fruit:
+    pass
+
+
+Fruit.__name__ = 1  # [non-str-assignment-to-dunder-name]
diff --git a/doc/data/messages/n/non-str-assignment-to-dunder-name/details.rst b/doc/data/messages/n/non-str-assignment-to-dunder-name/details.rst
deleted file mode 100644
index ab8204529..000000000
--- a/doc/data/messages/n/non-str-assignment-to-dunder-name/details.rst
+++ /dev/null
@@ -1 +0,0 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
diff --git a/doc/data/messages/n/non-str-assignment-to-dunder-name/good.py b/doc/data/messages/n/non-str-assignment-to-dunder-name/good.py
index c40beb573..ff55f1800 100644
--- a/doc/data/messages/n/non-str-assignment-to-dunder-name/good.py
+++ b/doc/data/messages/n/non-str-assignment-to-dunder-name/good.py
@@ -1 +1,5 @@
-# This is a placeholder for correct code for this message.
+class Fruit:
+    pass
+
+
+Fruit.__name__ = "FRUIT"
diff --git a/doc/data/messages/n/nonlocal-without-binding/bad.py b/doc/data/messages/n/nonlocal-without-binding/bad.py
new file mode 100644
index 000000000..6a166e09f
--- /dev/null
+++ b/doc/data/messages/n/nonlocal-without-binding/bad.py
@@ -0,0 +1,3 @@
+class Fruit:
+    def get_color(self):
+        nonlocal colors  # [nonlocal-without-binding]
diff --git a/doc/data/messages/n/nonlocal-without-binding/details.rst b/doc/data/messages/n/nonlocal-without-binding/details.rst
deleted file mode 100644
index ab8204529..000000000
--- a/doc/data/messages/n/nonlocal-without-binding/details.rst
+++ /dev/null
@@ -1 +0,0 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
diff --git a/doc/data/messages/n/nonlocal-without-binding/good.py b/doc/data/messages/n/nonlocal-without-binding/good.py
index c40beb573..cce884ac8 100644
--- a/doc/data/messages/n/nonlocal-without-binding/good.py
+++ b/doc/data/messages/n/nonlocal-without-binding/good.py
@@ -1 +1,5 @@
-# This is a placeholder for correct code for this message.
+class Fruit:
+    colors = ["red", "green"]
+
+    def get_color(self):
+        nonlocal colors
diff --git a/doc/data/messages/n/not-a-mapping/bad.py b/doc/data/messages/n/not-a-mapping/bad.py
new file mode 100644
index 000000000..79ca9215e
--- /dev/null
+++ b/doc/data/messages/n/not-a-mapping/bad.py
@@ -0,0 +1,5 @@
+def print_colors(**colors):
+    print(colors)
+
+
+print_colors(**list("red", "black"))  # [not-a-mapping]
diff --git a/doc/data/messages/n/not-a-mapping/details.rst b/doc/data/messages/n/not-a-mapping/details.rst
deleted file mode 100644
index ab8204529..000000000
--- a/doc/data/messages/n/not-a-mapping/details.rst
+++ /dev/null
@@ -1 +0,0 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
diff --git a/doc/data/messages/n/not-a-mapping/good.py b/doc/data/messages/n/not-a-mapping/good.py
index c40beb573..3de53ac5d 100644
--- a/doc/data/messages/n/not-a-mapping/good.py
+++ b/doc/data/messages/n/not-a-mapping/good.py
@@ -1 +1,5 @@
-# This is a placeholder for correct code for this message.
+def print_colors(**colors):
+    print(colors)
+
+
+print_colors(**dict(red=1, black=2))
diff --git a/doc/data/messages/p/possibly-unused-variable/bad.py b/doc/data/messages/p/possibly-unused-variable/bad.py
new file mode 100644
index 000000000..b64aee88b
--- /dev/null
+++ b/doc/data/messages/p/possibly-unused-variable/bad.py
@@ -0,0 +1,4 @@
+def choose_fruits(fruits):
+    print(fruits)
+    color = "red"  # [possibly-unused-variable]
+    return locals()
diff --git a/doc/data/messages/p/possibly-unused-variable/details.rst b/doc/data/messages/p/possibly-unused-variable/details.rst
deleted file mode 100644
index ab8204529..000000000
--- a/doc/data/messages/p/possibly-unused-variable/details.rst
+++ /dev/null
@@ -1 +0,0 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
diff --git a/doc/data/messages/p/possibly-unused-variable/good.py b/doc/data/messages/p/possibly-unused-variable/good.py
index c40beb573..095118328 100644
--- a/doc/data/messages/p/possibly-unused-variable/good.py
+++ b/doc/data/messages/p/possibly-unused-variable/good.py
@@ -1 +1,6 @@
-# This is a placeholder for correct code for this message.
+def choose_fruits(fruits):
+    current_locals = locals()
+    print(fruits)
+    color = "red"
+    print(color)
+    return current_locals
diff --git a/doc/data/messages/p/preferred-module/bad.py b/doc/data/messages/p/preferred-module/bad.py
new file mode 100644
index 000000000..a047ff36d
--- /dev/null
+++ b/doc/data/messages/p/preferred-module/bad.py
@@ -0,0 +1 @@
+import urllib  # [preferred-module]
diff --git a/doc/data/messages/p/preferred-module/details.rst b/doc/data/messages/p/preferred-module/details.rst
deleted file mode 100644
index ab8204529..000000000
--- a/doc/data/messages/p/preferred-module/details.rst
+++ /dev/null
@@ -1 +0,0 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
diff --git a/doc/data/messages/p/preferred-module/good.py b/doc/data/messages/p/preferred-module/good.py
index c40beb573..20b15530d 100644
--- a/doc/data/messages/p/preferred-module/good.py
+++ b/doc/data/messages/p/preferred-module/good.py
@@ -1 +1 @@
-# This is a placeholder for correct code for this message.
+import requests
diff --git a/doc/data/messages/p/preferred-module/pylintrc b/doc/data/messages/p/preferred-module/pylintrc
new file mode 100644
index 000000000..00ee49930
--- /dev/null
+++ b/doc/data/messages/p/preferred-module/pylintrc
@@ -0,0 +1,2 @@
+[IMPORTS]
+preferred-modules=urllib:requests,
diff --git a/doc/data/messages/r/redundant-returns-doc/bad.py b/doc/data/messages/r/redundant-returns-doc/bad.py
new file mode 100644
index 000000000..5d018db4c
--- /dev/null
+++ b/doc/data/messages/r/redundant-returns-doc/bad.py
@@ -0,0 +1,9 @@
+def print_fruits(fruits):  # [redundant-returns-doc]
+    """Print list of fruits
+
+    Returns
+    -------
+        str
+    """
+    print(fruits)
+    return None
diff --git a/doc/data/messages/r/redundant-returns-doc/details.rst b/doc/data/messages/r/redundant-returns-doc/details.rst
deleted file mode 100644
index ab8204529..000000000
--- a/doc/data/messages/r/redundant-returns-doc/details.rst
+++ /dev/null
@@ -1 +0,0 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
diff --git a/doc/data/messages/r/redundant-returns-doc/good.py b/doc/data/messages/r/redundant-returns-doc/good.py
index c40beb573..7f3eeebbb 100644
--- a/doc/data/messages/r/redundant-returns-doc/good.py
+++ b/doc/data/messages/r/redundant-returns-doc/good.py
@@ -1 +1,9 @@
-# This is a placeholder for correct code for this message.
+def print_fruits(fruits):
+    """Print list of fruits
+
+    Returns
+    -------
+        str
+    """
+    print(fruits)
+    return ",".join(fruits)
diff --git a/doc/data/messages/r/redundant-returns-doc/pylintrc b/doc/data/messages/r/redundant-returns-doc/pylintrc
new file mode 100644
index 000000000..4547f9811
--- /dev/null
+++ b/doc/data/messages/r/redundant-returns-doc/pylintrc
@@ -0,0 +1,2 @@
+[MAIN]
+load-plugins = pylint.extensions.docparams