From 18c75893c21a1f2ac6f06e836da91128849c8299 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rory=20O=E2=80=99Kane?= <rory@roryokane.com>
Date: Wed, 25 Mar 2020 12:18:11 -0400
Subject: [PATCH] docs: move `not nil` to the experimental page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When I heard that this feature existed, and found the 2018 changelog entry that said `not nil` was made experimental (https://github.com/nim-lang/Nim/blob/devel/changelogs/changelog_0_19_0.md#changes-affecting-backwards-compatibility), I looked for `not nil` documentation in https://nim-lang.org/docs/manual_experimental.html. When I didn’t find it there, I initially assumed the feature had no documentation. This change moves the documentation to where readers will expect it.

As well as moving the text to another file, I added instructions for enabling the experimental feature and tweaked some wording.
---
 doc/manual.rst              | 26 --------------------------
 doc/manual_experimental.rst | 30 ++++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 26 deletions(-)

diff --git a/doc/manual.rst b/doc/manual.rst
index 84cf1d8c97cd..5ef3f8d3a4e8 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -1838,32 +1838,6 @@ details like this when mixing garbage collected data with unmanaged memory.
 .. XXX finalizers for traced objects
 
 
-Not nil annotation
-------------------
-
-All types for which ``nil`` is a valid value can be annotated to
-exclude ``nil`` as a valid value with the ``not nil`` annotation:
-
-.. code-block:: nim
-  type
-    PObject = ref TObj not nil
-    TProc = (proc (x, y: int)) not nil
-
-  proc p(x: PObject) =
-    echo "not nil"
-
-  # compiler catches this:
-  p(nil)
-
-  # and also this:
-  var x: PObject
-  p(x)
-
-The compiler ensures that every code path initializes variables which contain
-non nilable pointers. The details of this analysis are still to be specified
-here.
-
-
 Procedural type
 ---------------
 A procedural type is internally a pointer to a procedure. ``nil`` is
diff --git a/doc/manual_experimental.rst b/doc/manual_experimental.rst
index 8c61c1217747..f65c0933b7a5 100644
--- a/doc/manual_experimental.rst
+++ b/doc/manual_experimental.rst
@@ -340,6 +340,36 @@ This operator will be matched against assignments to missing fields.
   a.b = c # becomes `.=`(a, b, c)
 
 
+Not nil annotation
+==================
+
+**Note:** This is an experimental feature. It can be enabled with
+``{.experimental: "notnil"}``.
+
+All types for which ``nil`` is a valid value can be annotated with the ``not
+nil`` annotation to exclude ``nil`` as a valid value:
+
+.. code-block:: nim
+  {.experimental: "notnil"}
+  
+  type
+    PObject = ref TObj not nil
+    TProc = (proc (x, y: int)) not nil
+
+  proc p(x: PObject) =
+    echo "not nil"
+
+  # compiler catches this:
+  p(nil)
+
+  # and also this:
+  var x: PObject
+  p(x)
+
+The compiler ensures that every code path initializes variables which contain
+non-nilable pointers. The details of this analysis are still to be specified
+here.
+
 
 Concepts
 ========