[libcxx-commits] [PATCH] D101098: [libcxx][docs] Add section for header layout and guidlines.

[Zoe Carver via Phabricator via libcxx-commits]

zoecarver updated this revision to Diff 339771.
zoecarver added a comment.

- Apply feedback


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D101098/new/

https://reviews.llvm.org/D101098

Files:
  libcxx/docs/Contributing.rst


Index: libcxx/docs/Contributing.rst
===================================================================
--- libcxx/docs/Contributing.rst
+++ libcxx/docs/Contributing.rst
@@ -55,6 +55,42 @@
 4. Create a submodule in ``include/module.modulemap`` for the new header.
 5. Update the ``include/CMakeLists.txt`` file to include the new header.
 
+Header layout
+=============
+
+Libc++ uses small and contained headers to implement various features. For example, if
+you were going to implement the ``std::ranges::size`` customization point object, you might
+consider creating a new header to house this new feature.
+
+There are a few things to keep in mind when creating new headers:
+
+* The current naming convention is exactly ``__<toplevelheadername>/<featurename>.h``
+  (note the double underscore mangling of the parent directory only and the ``.h`` file extension on the ``<featurename>.h`` header).
+  ``toplevelheadername`` must be the exact name of whatever header the Standard requires
+  to contain this feature, e.g. ``string`` or ``ranges`` or ``memory``. ``featurename``
+  should be the exact public identifier of the feature defined in this header, e.g.
+  ``iterator_traits`` or ``construct_at``. This should be the only feature defined in this
+  header.
+
+    - To clarify: the headers should only go one level deep. This means you could create a
+      header named ``__memory/shared_ptr.h``, but you couldn't create a header
+      ``__memory/smart_pointers/shared_ptr.h``.
+    - To clarify: defining exactly one public identifier per header, and naming the header
+      appropriately forbids headers such as ``__detail/utils.h``.
+* All sub-headers should be included by their parent header. To use the example above,
+  ``<ranges>`` must include the sub-header ``__ranges/size.h``, even if it
+  doesn't use ``ranges::size`` itself. This inclusion is mandatory because the standard
+  requires the top level header to provide these declarations. This rule falls out of the
+  more general "Include What You Use." You should never rely on some other header to
+  transitively include something that you need. If your header needs a definition of
+  ``iterator_traits``, then you should either ``#include <iterator>`` (exactly as user
+  code does), or, to improve compile time, ``#include <__iterator/iterator_traits.h>``.
+  You should never expect ``iterator_traits`` to be "pulled in" by any other header.
+* User code and test code, on the other hand, should never ``#include`` any of these
+  helper headers directly; they are intended as unstable implementation details of libc++.
+* The synopsis comment for a feature should still go in the parent header. Even if the
+  feature isn't implemented in the parent header.
+
 Exporting new symbols from the library
 ======================================
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D101098.339771.patch
Type: text/x-patch
Size: 2834 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20210422/ae077913/attachment.bin>