From 764c0b923740a3de46ac846230e82b3e942c0918 Mon Sep 17 00:00:00 2001 From: Jean-Louis Leroy Date: Sun, 23 Nov 2025 13:03:22 -0500 Subject: [PATCH] improve documentation --- .../virtual_ptr_alt/2/virtual_ptr_alt.cpp | 6 ++-- doc/modules/ROOT/pages/basics.adoc | 2 +- doc/modules/ROOT/pages/error_handling.adoc | 28 ++++++++++--------- doc/modules/ROOT/pages/friends.adoc | 6 ++-- doc/modules/ROOT/pages/headers.adoc | 4 +-- doc/modules/ROOT/pages/performance.adoc | 2 +- doc/modules/ROOT/pages/shared_libraries.adoc | 4 +-- 7 files changed, 27 insertions(+), 25 deletions(-) diff --git a/doc/modules/ROOT/examples/virtual_ptr_alt/2/virtual_ptr_alt.cpp b/doc/modules/ROOT/examples/virtual_ptr_alt/2/virtual_ptr_alt.cpp index 9fb6169..5a0cf02 100644 --- a/doc/modules/ROOT/examples/virtual_ptr_alt/2/virtual_ptr_alt.cpp +++ b/doc/modules/ROOT/examples/virtual_ptr_alt/2/virtual_ptr_alt.cpp @@ -22,7 +22,7 @@ struct Node { struct Variable : Node { Variable(int value) : v(value) { - vptr = boost::openmethod::default_registry::static_vptr; + vptr = registry::static_vptr; } int v; @@ -30,7 +30,7 @@ struct Variable : Node { struct Plus : Node { Plus(const Node& left, const Node& right) : left(left), right(right) { - vptr = boost::openmethod::default_registry::static_vptr; + vptr = registry::static_vptr; } const Node& left; @@ -39,7 +39,7 @@ struct Plus : Node { struct Times : Node { Times(const Node& left, const Node& right) : left(left), right(right) { - vptr = boost::openmethod::default_registry::static_vptr; + vptr = registry::static_vptr; } const Node& left; diff --git a/doc/modules/ROOT/pages/basics.adoc b/doc/modules/ROOT/pages/basics.adoc index 97804d1..8e6889d 100644 --- a/doc/modules/ROOT/pages/basics.adoc +++ b/doc/modules/ROOT/pages/basics.adoc @@ -2,7 +2,7 @@ [#basics] -An _open-method_ is a free-standing function that takes one or more _virtual_ +An _open-method_ is a free-standing function that has one or more _virtual_ _parameters_. When it is called, it forwards to an _overrider_ selected from a set by examining the dynamic types of the virtual parameters. diff --git a/doc/modules/ROOT/pages/error_handling.adoc b/doc/modules/ROOT/pages/error_handling.adoc index 5892d61..e954e16 100644 --- a/doc/modules/ROOT/pages/error_handling.adoc +++ b/doc/modules/ROOT/pages/error_handling.adoc @@ -1,15 +1,14 @@ [#error_handling] -Errors can occur during `initialize`, or during method dispatch, if the -method's registry contains the `runtime_checks` policy. If the registry -contains an `error_handler` policy, its `error_handler::error` member -function is called with a variant containing an error object, before terminating -the program with a call to `abort`. `default_registry` contains such a -policy: `default_error_handler`. It wraps the error object in a variant, and -calls a handler via a `std::function`. By default, it prints a short description -of the error to `stderr`, but this can be changed, for example, to throw an -exception: +Errors can occur during `initialize`, or during method dispatch, if the method's +registry contains the `runtime_checks` policy. If the registry contains an +`error_handler` policy, its `error_handler::error` member function is called +with an error object, before terminating the program with a call to `abort`. +`default_registry` contains such a policy: `default_error_handler`. It wraps the +error object in a variant, and calls a handler via a `std::function`, +initialized to a function that prints a short description of the error to +`stderr`. The function can be changed, for example, to throw an exception: [source,c++] ---- @@ -43,11 +42,14 @@ spin Stock policy `throw_error_handler` does this for all the error types: -```c++ namespace boost::openmethod::policies { +```c++ +namespace boost::openmethod::policies { -struct throw_error_handler : error_handler { template - [[noreturn]] static auto error(const Error& error) -> void { throw - error; } +struct throw_error_handler : error_handler { + template + [[noreturn]] static auto error(const Error& error) -> void { + throw error; + } }; } // namespace boost::openmethod::policies diff --git a/doc/modules/ROOT/pages/friends.adoc b/doc/modules/ROOT/pages/friends.adoc index 9e94a47..dbe82d4 100644 --- a/doc/modules/ROOT/pages/friends.adoc +++ b/doc/modules/ROOT/pages/friends.adoc @@ -5,9 +5,9 @@ Note;; This section uses overrider containers, described in the xref:headers.adoc[Headers] section. -`friend` is a controversial feature. OpenMethod aims to interact well with -all of C++, as much as feasible for a library, and leave the user the choice of -using `friend`, or not. +`friend` is a controversial feature. OpenMethod aims to interact well with all +of C++, as much as feasible for a library, and leaves the choice of using +`friend`, or not, to the user. Let's consider yet another variation of the `pay` example. This time, we want to update a `balance` variable in a `Payroll` class, when an employee is paid. Thus diff --git a/doc/modules/ROOT/pages/headers.adoc b/doc/modules/ROOT/pages/headers.adoc index efd43ef..8dd0edd 100644 --- a/doc/modules/ROOT/pages/headers.adoc +++ b/doc/modules/ROOT/pages/headers.adoc @@ -8,8 +8,8 @@ implementation files. Let's use a payroll application as an example. We have two roles: `Employee` and `Salesman`, and a `pay` method that computes the monthly pay of an employee. We -want to override and call `pay` from from multiple translation units, so we put -it in a header: +want to override and call `pay` from multiple translation units, so we put it in +a header: [source,c++] ---- diff --git a/doc/modules/ROOT/pages/performance.adoc b/doc/modules/ROOT/pages/performance.adoc index f7c450e..1f14b20 100644 --- a/doc/modules/ROOT/pages/performance.adoc +++ b/doc/modules/ROOT/pages/performance.adoc @@ -67,7 +67,7 @@ than calling the equivalent virtual function, with an empty body and no other arguments. In most real programs, the overhead would be unnoticeable. *However*, `call_via_ref` does two things: it constructs a `virtual_ptr` -from a `const Node&`; and then it calls the method. +from a `const Node&`, then it calls the method. The construction of the `virtual_ptr` is the costly part. It performs a lookup in a perfect hash table, indexed by pointers to `std::type_info`, to find the diff --git a/doc/modules/ROOT/pages/shared_libraries.adoc b/doc/modules/ROOT/pages/shared_libraries.adoc index 92c99d0..9da38e6 100644 --- a/doc/modules/ROOT/pages/shared_libraries.adoc +++ b/doc/modules/ROOT/pages/shared_libraries.adoc @@ -79,7 +79,7 @@ include::{shared}/dynamic_main.cpp[tag=unload] ### Windows -If we try the aboveexample on Windows, the result is disappointing: +If we try the example on Windows, the result is disappointing: ``` Before loading the shared library. @@ -98,7 +98,7 @@ they add overriders to _their_ copy of the method (the `method::fn` static variable for the given name and signature). They are ignored when the main program calls `initialize`. -Likewise, `BOOST_OPENMETHOD_CLASSES(Tiger, Carnivore);` in the DLL adds `Tiger` +Likewise, `BOOST_OPENMETHOD_CLASSES(Tiger, Carnivore)` in the DLL adds `Tiger` to the DLL's copy of the registry. For the perspective of the program's registry, the class does not exist.