[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)

[Chuanqi Xu via cfe-commits]

================
@@ -610,6 +610,345 @@ the following style significantly:
 
 The key part of the tip is to reduce the duplications from the text includes.
 
+Ideas for converting to modules
+-------------------------------
+
+For new libraries, we encourage them to use modules completely from day one if possible.
+This will be pretty helpful to make the whole ecosystems to get ready.
+
+For many existing libraries, it may be a breaking change to refactor themselves
+into modules completely. So that many existing libraries need to provide headers and module
+interfaces for a while to not break existing users.
+Here we provide some ideas to ease the transition process for existing libraries.
+**Note that the this section is only about helping ideas instead of requirement from clang**.
+
+Let's start with the case that there is no dependency or no dependent libraries providing
+modules for your library.
+
+ABI non-breaking styles
+~~~~~~~~~~~~~~~~~~~~~~~
+
+export-using style
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: c++
+
+  module;
+  #include "header_1.h"
+  #include "header_2.h"
+  ...
+  #include "header_n.h"
+  export module your_library;
+  export namespace your_namespace {
+    using decl_1;
+    using decl_2;
+    ...
+    using decl_n;
+  }
+
+As the example shows, you need to include all the headers containing declarations needs
+to be exported and `using` such declarations in an `export` block. Then, basically,
+we're done.
+
+export extern-C++ style
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: c++
+
+  module;
+  #include "third_party/A/headers.h"
+  #include "third_party/B/headers.h"
+  ...
+  #include "third_party/Z/headers.h"
+  export module your_library;
+  #define IN_MODULE_INTERFACE
+  extern "C++" {
+    #include "header_1.h"
+    #include "header_2.h"
+    ...
+    #include "header_n.h"
+  }
+
+Then in your headers (from ``header_1.h`` to ``header_n.h``), you need to define the macro:
+
+.. code-block:: c++
+
+  #ifdef IN_MODULE_INTERFACE
+  #define EXPORT export
+  #else
+  #define EXPORT
+  #endif
+
+And you should put ``EXPORT`` to the beginning of the declarations you want to export.
+
+Also it is suggested to refactor your headers to include thirdparty headers conditionally:
+
+.. code-block:: c++
+
+  + #ifndef IN_MODULE_INTERFACE
+  #include "third_party/A/headers.h"
+  + #endif
+
+  #include "header_x.h"
+
+  ...
+
+This may be helpful to get better diagnostic messages if you forgot to update your module 
+interface unit file during maintaining.
+
+The reasoning for the practice is that the declarations in the language linkage are considered
+to be attached to the global module. So the ABI of your library in the modular version
+wouldn't change.
+
+While this style looks not as convenient as the export-using style, it is easier to convert 
+to other styles.
+
+ABI breaking style
+~~~~~~~~~~~~~~~~~~
+
+The term ``ABI breaking`` sounds terrifying generally. But you may want it here if you want
+to force your users to introduce your library in a consistent way. E.g., they either include
+your headers all the way or import your modules all the way.
+The style prevents the users to include your headers and import your modules at the same time
+in the same repo.
----------------
ChuanqiXu9 wrote:

For example, if the library is in a closed-ended ecosystem (e.g., only available to an organization internally), then  we want to provide modules interfaces for the library and we want our users to avoid the accidental performance cost due to mixing use of include and import, then such pattern helps. In case, the user repo A depends on a repo B and repo B include the modularized library, the repo A can reach out repo B to refactor itself. I feel such workflow can be understandable in a close ended organization.

 It will bring some burden to users initially, but in the end it would bring better quality. I understand this is not a helpful universally. But I feel it may be helpful to people who want to bring stronger requirement to the usage of their codes.

https://github.com/llvm/llvm-project/pull/80687