update documentation

doc/source/changelog.rst

@@ -13,7 +13,7 @@ PyPy support lags CPython support.
 2023-01-21: 2.4.2
 -----------------
 
-* Added a generic "cppyy.default" object
+* Added a generic ``cppyy.default`` object
 * Support explicitly created initializer lists as arguments
 * Pass instances by-ref in Numba traces
 * Support non-POD by-value returns in Numba traces
@@ -24,9 +24,9 @@ PyPy support lags CPython support.
 * Added ``nullptr`` comparisons for for typed ``nullptr``
 * Support for ``using`` pointer types as template arguments
 * Walk the full inheritance tree to find the overloads
-* Allow __destruct__ override in Python derived class
-* Allow NULL function pointers to be returned as std::function objects
-* Add Python traceback to C++ exception what()
+* Allow ``__destruct__`` override in Python derived class
+* Allow ``NULL`` function pointers to be returned as ``std::function`` objects
+* Add Python traceback to C++ exception ``what()``
 
 
 2022-10-03: 2.4.1

doc/source/classes.rst

@@ -88,8 +88,14 @@ There should not be a reason to call a destructor directly in CPython, but
 PyPy uses a garbage collector and that makes it sometimes useful to destruct
 a C++ object where you want it destroyed.
 Destructors are accessible through the conventional ``__destruct__`` method.
-Accessing an object after it has been destroyed will result in a Python
-``ReferenceError`` exception.
+If a Python-side derived class overrides ``__destruct__``, that method will
+be called when the instance gets deleted in C++.
+The Python destructor, ``__del__``, gets called when the Python proxy goes
+away, which will only delete the C++ instance if owned by Python.
+Note that ``__del__`` is not guaranteed to be called, it may e.g. be skipped
+on program shutdown or because of an outstanding exception.
+Accessing an object after it has been destroyed using ``__destruct__`` will
+result in a Python ``ReferenceError`` exception.
 
 
 `Inheritance`

doc/source/lowlevel.rst

@@ -292,4 +292,18 @@ The low-level module adds the following functions:
     >>>
 
 
+`argc/argv`
+-----------
+
+C/C++'s ``main`` function can take the number of command line arguments
+(``argc``) and their values (``argv``) as function arguments.
+A common idiom has these values subsequently passed on to the entry point of
+e.g. a framework or library.
+Since the type of ``argv`` in particular (``char*[]``) is clunky to work with
+in Python, the low level module contains two convenient helper functions,
+ ``ll.argc()`` and ``ll.argv()``, that convert the command line arguments as
+provided by Python's ``sys`` module, into typed values that are can be passed
+to by C/C++.
+
+
 .. _`ctypes module`: https://docs.python.org/3/library/ctypes.html

doc/source/misc.rst

@@ -75,6 +75,11 @@ Global Interpreter Lock (GIL) release.
   the actual C++ name (as opposed to ``__name__`` which has the Python name).
   This can be useful for template instantiations, documentation, etc.
 
+* ``__cpp_template__``: a back-reference to the template used to instantiate
+  a templated class.
+  This variable only exists if the class was dynamically instantiated from
+  Python at least once.
+
 
 `STL algorithms`
 ----------------
@@ -175,3 +180,7 @@ available, but still saves some typing in may cases.
   For clarity of intent, it is recommended to use this instead of ``None``
   (or the integer ``0``, which can serve in some cases), as ``None`` is better
   understood as ``void`` in C++.
+
+* **default value**: Represented with The untyped ``cppyy.default``.
+  The generic value ``cppyy.default`` will convert to the type specific default
+  value (per C++ rules)  when used as a function argument or in assignment.