add caveat language re MicroPython libraries; other slight changes

dhalbert · dhalbert · commit 59615fc9938e · 2018-05-22T20:49:08.000-04:00
diff --git a/README.rst b/README.rst
@@ -108,9 +108,10 @@ CircuitPython:
 -  supports only SAMD21, SAMD51, and ESP8266 ports. An nRF port is under
    development.
 -  tracks MicroPython's releases (not master).
--  Longints (arbitrary-length integers) are turned on for most Express builds
-   (those boards with SPI flash chips external to the microcontroller),
-   but not for boards without SPI flash, for space reasons.
+-  Longints (arbitrary-length integers) are enabled for most M0
+   Express boards (those boards with SPI flash chips external
+   to the microcontroller), and for all M4 builds.
+   Longints are disabled on other boards due to lack of flash space.
 
 Behavior
 ~~~~~~~~
diff --git a/docs/library/gc.rst b/docs/library/gc.rst
@@ -1,6 +1,8 @@
 :mod:`gc` -- control the garbage collector
 ==========================================
 
+.. include:: ../templates/unsupported_in_circuitpython.inc
+
 .. module:: gc
    :synopsis: control the garbage collector
 
diff --git a/docs/library/index.rst b/docs/library/index.rst
@@ -1,21 +1,30 @@
 .. _micropython_lib:
 
-CircuitPython libraries
+MicroPython libraries
 =====================
 
 Python standard libraries and micro-libraries
 ---------------------------------------------
 
-These libraries are the same or are subsets or slight variants of the standard Python libraries.
+These libraries are inherited from MicroPython.
+They are similar to the standard Python libraries with the same name
+or with the "u" prefix dropped.
+They implement a subset of or a variant of the corresponding
+standard Python library.
 
-MicroPython prefixed many of these libraries with ``u``. In CircuitPython, those
-that are subsets or the same as the standard Python libraries have been or will be renamed
-to their original names.
-Our aspiration is that code written in CircuitPython
-that uses Python standard libraries will be runnable on CPython without changes.
-But we may fall short of this goal in some cases.
+.. warning::
 
-Some of the libraries below are not enabled on CircuitPython builds with
+   Though these MicroPython-based libraries are available in CircuitPython,
+   their functionality may change in the future, perhaps significantly.
+   As CircuitPython continues to develop, new versions of these libraries will
+   be created that are more compliant with the standard Python libraries.
+   You may need to change your code later if you rely
+   on any non-standard functionality they currently provide.
+
+CircuitPython's goal long-term goalis that code written in CircuitPython
+using Python standard libraries will be runnable on CPython without changes.
+
+Some libraries below are not enabled on CircuitPython builds with
 limited flash memory, usually on non-Express builds:
 ``uerrno``, ``ure``.
 
@@ -51,17 +60,18 @@ Not all of these are enabled on all WiFi-capable ports.
 Omitted functions in the ``string`` library
 -------------------------------------------
 
-A few string operations are not enabled on CircuitPython builds with
-limited flash memory, usually on non-Express builds:
+A few string operations are not enabled on CircuitPython
+M0 non-Express builds, due to limited flash memory:
 ``string.center()``, ``string.partition()``, ``string.splitlines()``,
 ``string.reversed()``.
 
 
 CircuitPython/MicroPython-specific libraries
 ------------------------------
 
-Functionality specific to the CircuitPython (MicroPython) implementation is available in
-the following libraries.
+Functionality specific to the CircuitPython/MicroPython implementation is available in
+the following libraries. These libraries may change signficantly or be removed in future
+versions of CircuitPtyon.
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/library/struct.rst b/docs/library/struct.rst
@@ -1,6 +1,8 @@
 :mod:`struct` -- pack and unpack primitive data types
 ======================================================
 
+.. include:: ../templates/unsupported_in_circuitpython.inc
+
 .. module:: struct
    :synopsis: pack and unpack primitive data types
 
diff --git a/docs/library/sys.rst b/docs/library/sys.rst
@@ -1,6 +1,8 @@
 :mod:`sys` -- system specific functions
 =======================================
 
+.. include:: ../templates/unsupported_in_circuitpython.inc
+
 .. module:: sys
    :synopsis: system specific functions
 
@@ -98,7 +100,7 @@ Constants
    usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it
    is an identifier of the chip on a board, e.g. ``"MicroChip SAMD51"``.
    It thus can be used to distinguish one board from another.
-   If you need to check whether your program runs on MicroPython (vs other
+   If you need to check whether your program runs on CircuitPython (vs other
    Python implementation), use `sys.implementation` instead.
 
 .. data:: stderr
diff --git a/docs/templates/unsupported_in_circuitpython.inc b/docs/templates/unsupported_in_circuitpython.inc
@@ -1,5 +1,8 @@
 .. warning::
 
-    This module is inherited from MicroPython and may not work in CircuitPython
-    as documented or at all! If they do work, they may change at any time. It is
-    unsupported.
+   Though this MicroPython-based library is available for use in CircuitPython,
+   its functionality may change in the future, perhaps significantly.
+   As CircuitPython continues to develop, it may be changed
+   to comply more closely with the corresponding standard Python library.
+   You may need to change your code later if you rely
+   on any non-standard functionality it currently provides.
