Minor documentation fixes (#11642)

* Enhance documentation around `dirs`

* Add documentation warning about include_subdirs and lexer/parsers

Signed-off-by: Raphaël Monat <[email protected]>

Author: rmonat

doc/reference/dune/dirs.rst

@@ -27,3 +27,14 @@ Dune will not scan a directory that isn't included in this stanza. Any contained
 ``dune`` (or other special) files won't be interpreted either and will be
 treated as raw data. It is however possible to depend on files inside ignored
 subdirectories.
+
+.. warning::
+
+  Directory names should not contain any trailing slashes.
+
+If you want to exclude a subdirectory, such as `foo/bar`, you need to use the
+:doc:`/reference/dune/subdir` stanza:
+
+.. code:: dune
+
+  (subdir foo (dirs :standard \ bar)) ;; exclude foo/bar

doc/reference/dune/include_subdirs.rst

@@ -35,3 +35,9 @@ following stanzas:
 - ``library``
 - ``executable(s)``
 - ``test(s)``
+
+.. warning::
+
+   Currently the `(ocamllex)`, `(ocamlyacc)` and `(menhir)` stanzas do not work
+   well in combination with `(include_subdirs qualified)`. See `this issue
+   <https://github.com/ocaml/dune/issues/11119>`_ for more information.