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

[Zoe Carver via Phabricator via libcxx-commits]

zoecarver created this revision.
zoecarver added reviewers: Quuxplusone, ldionne, cjdb, Mordante.
zoecarver requested review of this revision.
Herald added a project: libc++.
Herald added a subscriber: libcxx-commits.
Herald added a reviewer: libc++.

Repository:
  rG LLVM Github Monorepo

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,28 @@
 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 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``.
+* All sub-directories should be mangled with a double underscore. Conversely, headers
+  that live in these directories should not be mangled.
+* Headers should contain specific features. A header such as ``__detail/utils.h`` might
+  turn into a dumping ground for "random" utilities. This is counterproductive and actually
+  makes things harder to find.
+* All sub-headers should be included by their parent header. To use the example above,
+  it is imperative that ``<ranges>`` includes the sub-header ``__ranges/size.h``. Or, to use
+  another example, ``<iterator>`` must include ``__iterator/iterator_traits.h``, even if it
+  doesn't use ``iterator_traits`` itself.
+
 Exporting new symbols from the library
 ======================================
 


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