Document re_export field

doc/concepts.rst

@@ -347,6 +347,32 @@ all the literals evaluate to true. It is an error if none of the clauses are
 selectable. You can add a fallback by adding a clause of the form ``(->
 <file>)`` at the end of the list.
 
+Re-exported dependencies
+------------------------
+
+A dependency ``foo`` may be marked as always *re-exported* using the
+following syntax:
+
+.. code:: scheme
+
+   (re_export foo)
+
+For insance:
+
+.. code:: scheme
+
+   (library
+    (name bar)
+    (libraries (re_export foo)))
+
+This states that this library explicitly re-exports the interface of
+``foo``.  Concretely, when something depends on ``bar`` it will also
+be able to see ``foo`` independently of whether :ref:`implicit
+transitive dependencies<implicit_transitive_deps>` are allowed or
+not. When they are allowed, which is the default, all transitive
+dependencies are visible whether they are marked as re-exported or
+not.
+
 .. _preprocessing-spec:
 
 Preprocessing specification

doc/dune-files.rst

@@ -56,6 +56,19 @@ Note that you must use ``threads.posix`` instead of ``threads`` when using this
 mode. This is not an important limitation as ``threads.vm`` are deprecated
 anyways.
 
+In some situations, it's desirable to selectively preserve the
+behavior of transitive dependencies being available to users of a
+library. For example, if we define a library ``foo_more``, that
+extends ``foo``, we might want users of ``foo_more`` to immediately
+have ``foo`` available as well. To do this, we must define the
+dependency on ``foo`` as re-exported:
+
+.. code:: scheme
+
+   (library
+    (name foo_more)
+    (libraries (re_export foo)))
+
 .. _wrapped-executables:
 
 wrapped_executables