Document re_export field

doc/concepts.rst

@@ -347,6 +347,20 @@ 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 *re-exportable* using the following
+syntax:
+
+.. code:: scheme
+
+   (re_export foo)
+
+This states that this library explicitly re-exports the interface of ``foo``.
+This is primarily useful when :ref:`implicit transitive dependencies<implicit_transitive_deps>`
+are disallowed, so it's documented along with the general feature.
+
 .. _preprocessing-spec:
 
 Preprocessing specification

doc/dune-files.rst

@@ -56,6 +56,18 @@ 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'd like 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