From 285ef3e64a8b3e122a379556ec38dd0c10944a74 Mon Sep 17 00:00:00 2001
From: Michael Hatherly <michaelhatherly@gmail.com>
Date: Sun, 21 Aug 2016 06:21:21 +0200
Subject: [PATCH] Add note about docstrings for aliases (#18157)

As mentioned in https://github.com/JuliaLang/julia/pull/18041#issuecomment-241189817
docstrings attached to aliases of functions should be avoided where possible.
(cherry picked from commit 3ed55a404eb425229f0556a4f7fdc614008c0ed6)
---
 doc/manual/documentation.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/doc/manual/documentation.rst b/doc/manual/documentation.rst
index a6d481f340a58..b40dedf5038a0 100644
--- a/doc/manual/documentation.rst
+++ b/doc/manual/documentation.rst
@@ -441,6 +441,32 @@ Global Variables
 
 Adds docstring ``"..."`` to the ``Binding``\ s ``a``, ``b``, and ``c``.
 
+.. note::
+
+    When a ``const`` definition is only used to define an alias of another definition, such
+    as is the case with the function ``div`` and its alias ``÷`` in ``Base``, do not
+    document the alias and instead document the actual function.
+
+    If the alias is documented and not the real definition then the docsystem (``?`` mode)
+    will not return the docstring attached to the alias when the real definition is
+    searched for.
+
+    For example you should write
+
+    .. code-block:: julia
+
+        "..."
+        f(x) = x + 1
+        const alias = f
+
+    rather than
+
+    .. code-block:: julia
+
+        f(x) = x + 1
+        "..."
+        const alias = f
+
 .. code-block:: julia
 
     "..."