Changes after David's Review

Author: QuillPusher

docs/UsingCppInterOp.rst

@@ -65,40 +65,44 @@ robust (simple function calls, no inheritance, etc.). The goal is to make it as
 close to the compiler API as possible, and each routine should do just one thing.
 that it was designed for.
 
-Further Enhancing the Dynamic/Automatic bindings in CPPYY
-=========================================================
+How cppyy relates to CppInterOp and how it works
+================================================
 
-CppInterOp ties into the following major enhancements in cppyy:
+CppInterOp ties into several `enhancements in cppyy`_, following are a few:
 
--  **Reducing dependencies** of cppyy to minimize code bloat and make it
-   faster.
-
--  A **cppyy-Style Library** (i.e., CppInterOp) that enables interoperability
+1. **CppInterOp is a cppyy-inspired Library** that enables interoperability
    with C++ code, bringing the speed and efficiency of C++ to simpler, more
    interactive languages like Python.
 
+2. **Reducing dependencies** of cppyy to minimize code bloat and make it
+   faster.
+
+3. **LLVM Integration**: CppInterOp's integration with LLVM's Clang-REPL
+   component (that can then be used as a runtime compiler for CPPYY), will
+   further enhance CPPYY's performance.
+
+**CppInterOp is a cppyy-inspired Library**
+
+A major use case for CppInterOp is the CPPYY service. CPPYY is an automatic
+run-time bindings generator for Python and C++, and supports a wide range of
+C++ features (e.g., template instantiation). It operates on demand and
+generates only what is necessary. It requires a compiler (Cling or Clang-REPL).
+that can be available during programme runtime.
+
 **Reducing Dependencies**
 
 Recent work done on cppyy has been focused on removing unnecessary
 dependencies on domain-specific infrastructure (e.g., the ROOT
 framework). The idea was to convert the cppyy-backend to use Cling
-directly (instead of ROOT meta), and then use it in cppyy.
+directly (instead of `ROOT meta`_), and then use it in cppyy.
 
-Only a small set of APIs are needed to connect to the interpreter, since
-other APIs are already available in the standard compiler. This is what
-led to the creation of CppInterOp (a library of helper functions), that
-helped extract out things that were unnecessary for cppyy, etc.
+Only a small set of APIs are needed to connect to the interpreter (Cling),
+since other APIs are already available in the standard compiler. This is what
+led to the creation of CppInterOp (a library of helper functions), that helped
+extract out things that were unnecessary for cppyy, etc.
 
-The API surface is now incomparably smaller and simpler than what it
-used to be.
-
-**cppyy-Style Library**
-
-The main use case for CppInterOp is the CPPYY service. CPPYY is an
-automatic run-time bindings generator for Python and C++, and supports a wide
-range of C++ features (e.g., template instantiation). It operates on demand and
-generates only what is necessary. It requires a compiler (Cling or Clang-REPL).
-that can be available during programme runtime.
+The cppyy API surface is now incomparably smaller and simpler than what it used
+to be.
 
 **LLVM Integration**
 
@@ -110,8 +114,8 @@ performance in the following ways:
 - *Simpler codebase:* The removal of string parsing logic will lead to a
   simpler code base.
 
-- *LLVM Integration:* The CppInterOp interfaces will be part of the LLVM
-  toolchain (as part of Clang-REPL).
+- *Built into the LLVM toolchain:* The CppInterOp interfaces will be part of
+  the LLVM toolchain (as part of Clang-REPL).
 
 - *Better C++ Support:* C++ features such as Partial Template Specialisation
   will be available through CppInterOp.
@@ -124,14 +128,14 @@ performance in the following ways:
 
 **Making C++ More Social**
 
-cppyy serves as a great proof of concept for other languages to become
-interoperable with C++ (using CppInterOp). This helps a lot of data
-scientists that are working with legacy C++ code and would like to
-migrate to simpler, more interactive languages.
+cppyy is the first use case demonstrating how CppInterOp can enable C++ to be
+more easily interoperable with other languages. This helps many data scientists
+that are working with legacy C++ code and would like to use simpler, more
+interactive languages.
 
-The goal of this research is to eventually land these interoperability
-tools (including CppInterOp) to greater communities like LLVM and Clang,
-to enable C++ to interact with other languages besides Python.
+The goal of these enhancements is to eventually land these interoperability
+tools (including CppInterOp) to greater communities like LLVM and Clang, to
+enable C++ to interact with other languages besides Python.
 
 Example: Template Instantiation
 -------------------------------
@@ -190,11 +194,29 @@ code.
 How cppyy components interact with each other
 ---------------------------------------------
 
-**cppyy-backend**
+cppyy is made up of the following packages: 
+
+- A frontend: cppyy, 
 
-The ``cppyy-backend`` forms a layer over ``cppyy``, modifying some
-functionality to provide the functions required for ``CPyCppyy``. It also adds
-some `utilities`_ to help with repackaging and redistribution.
+- A backend: cppyy-backend, and 
+
+- An extension: CPyCppyy.
+
+Besides these, the ``CppInterOp`` library serves as an additional layer on top
+of Cling/Clang-REPL that helps these packages in communicating with C++ code.
+
+**1. cppyy-backend**
+
+The `cppyy-backend`_ pacakge forms a layer over ``cppyy``, for example,
+modifying some functionality to provide the functions required for
+``CPyCppyy``. 
+
+  `CPyCppyy`_ is a CPython extension module built on top of the same backend
+  API as PyPy/_cppyy. It thus requires the installation of the cppyy-backend
+  for use, which will pull in Cling. 
+
+``cppyy-backend`` also adds some `utilities`_ to help with repackaging and
+redistribution.
 
 For example, it initializes the interpreter (using the
 ``clingwrapper::ApplicationStarter`` function), adds the required
@@ -205,22 +227,22 @@ CPyCppyy work.
 These changes help ensure that any change in ``cppyy`` doesn’t directly
 affect ``CPyCppyy``, and the API for ``CPyCppyy`` remains unchanged.
 
-**CPyCppyy**
+**2. CPyCppyy**
 
-``CPyCppyy`` uses the functionality provided by ``cppyy-backend`` and
-provides Python objects for C++ entities. ``CPyCppyy`` uses separate
-proxy classes for each type of object. It also includes helper classes,
-for example, ``Converters.cxx`` helps convert Python type objects to C++
-type objects, while ``Executors.cxx`` is used to execute a function and
-convert its return value to a Python object, so that it can be used
-inside Python.
+The ``CPyCppyy`` package uses the functionality provided by ``cppyy-backend``
+and provides Python objects for C++ entities. ``CPyCppyy`` uses separate proxy
+classes for each type of object. It also includes helper classes, for example,
+``Converters.cxx`` helps convert Python type objects to C++ type objects, while
+``Executors.cxx`` is used to execute a function and convert its return value to
+a Python object, so that it can be used inside Python.
 
-**cppyy**
+**3. cppyy**
 
-cppyy provides the front-end for Python. It is `included`_ in code to import
-cppyy in Python. It initializes things on the backend side, provides helper
-functions (e.g., ``cppdef()``, ``cppexec()``, etc.) that the user can utilize,
-and it calls the relevant backend functions required to initialize cppyy.
+The cppyy package provides the front-end for Python. It is `included in code`_
+(using ``import cppyy``) to import cppyy in Python. It initializes things on
+the backend side, provides helper functions (e.g., ``cppdef()``, ``cppexec()``,
+etc.) that the user can utilize, and it calls the relevant backend functions
+required to initialize cppyy.
 
 
 Further Reading
@@ -243,28 +265,43 @@ Further Reading
 
 **Credits:**
 
--  `Baidyanath Kundu <https://github.com/sudo-panda>`_ (Princeton
-   University) for his research work on cppyy and Numba for `Compiler
-   Research Organization <https://compiler-research.org/>`_.
-
--  `Vassil Vasilev <https://github.com/vgvassilev>`_ (Princeton
-   University) for mentoring Baidyanath and continuing this research
-   with `Aaron Jomy <https://github.com/maximusron>`_.
+-  `Wim Lavrijsen <https://github.com/wlav>`_ (Lawrence Berkeley National Lab.)
+   for his original work in cppyy and mentorship towards student contributors.
 
--  `Wim Lavrijsen <https://github.com/wlav>`_ (Lawrence Berkeley
-   National Lab) cppyy’s original contributor.
+-  `Vassil Vasilev <https://github.com/vgvassilev>`_ (Princeton University)
+   for his mentorship towards Compiler Research Org's student contributors.
 
+-  `Baidyanath Kundu <https://github.com/sudo-panda>`_ (Princeton University)
+   for his research work on cppyy and Numba with `Compiler Research Organization`_ 
+   (as discussed in this document).
+   
+- `Aaron Jomy <https://github.com/maximusron>`_ (Princeton University) for
+  continuing this research work with `Compiler Research Organization`_.
 
 In case you haven't already installed CppInterop, please do so before proceeding
 with the Installation And Usage Guide.
 :doc:`Installation and usage <InstallationAndUsage>`
 
+.. _Compiler Research Organization: https://compiler-research.org/
+
 .. _upstream cppyy: https://github.com/wlav/cppyy
 
 .. _wlav: https://github.com/wlav
 
 .. _utilities: https://cppyy.readthedocs.io/en/latest/utilities.html
 
-.. _included: https://cppyy.readthedocs.io/en/latest/starting.html
+.. _included in code: https://cppyy.readthedocs.io/en/latest/starting.html
+
+.. _sudo-panda: https://github.com/sudo-panda
+
+.. _cppyy: https://cppyy.readthedocs.io/en/latest/index.html
+
+.. _CppInterOp: https://github.com/compiler-research/CppInterOp
+
+.. _ROOT meta: https://github.com/root-project/root/tree/master/core/meta
+
+.. _enhancements in cppyy: https://arxiv.org/abs/2304.02712
+
+.. _CPyCppyy: https://github.com/wlav/CPyCppyy
 
-.. _sudo-panda: https://github.com/sudo-panda
+.. _cppyy-backend: https://github.com/wlav/cppyy-backend