Update documentation

Author: mingxwa

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.28)
 
-project(msft_proxy4 VERSION 4.0.2 LANGUAGES CXX)
+project(msft_proxy4 VERSION 4.1.0 LANGUAGES CXX)
 add_library(msft_proxy4 INTERFACE)
 set_target_properties(msft_proxy4 PROPERTIES EXPORT_NAME proxy)
 add_library(msft_proxy4::proxy ALIAS msft_proxy4)

MODULE.bazel

@@ -1,6 +1,6 @@
 module(
     name = "proxy",
-    version = "4.0.2",
+    version = "4.1.0",
 )
 
 bazel_dep(name = "platforms", version = "1.1.0")

README.md

@@ -216,7 +216,7 @@ The "Proxy" library is a self-contained solution for runtime polymorphism in C++
 - **Concepts**: To facilitate template programming with "Proxy", 3 concepts are exported from a facade type. Namely, [`proxiable`](https://ngcpp.github.io/proxy/spec/proxiable), [`proxiable_target`](https://ngcpp.github.io/proxy/spec/proxiable_target) and [`inplace_proxiable_target`](https://ngcpp.github.io/proxy/spec/inplace_proxiable_target).
 - **Allocator awareness**: [function template `allocate_proxy`](https://ngcpp.github.io/proxy/spec/allocate_proxy) is able to create a `proxy` from a value with any custom allocator. In C++11, [`std::function`](https://en.cppreference.com/w/cpp/utility/functional/function) and [`std::packaged_task`](https://en.cppreference.com/w/cpp/thread/packaged_task) had constructors that accepted custom allocators for performance tuning, but these were [removed in C++17](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0302r1.html) because "the semantics are unclear, and there are technical issues with storing an allocator in a type-erased context and then recovering that allocator later for any allocations needed during copy assignment". These issues do not apply to `allocate_proxy`.
 - **Configurable constraints**: [`facade_builder`](https://ngcpp.github.io/proxy/spec/basic_facade_builder) provides full support for constraints configuration, including memory layout (by [`restrict_layout`](https://ngcpp.github.io/proxy/spec/basic_facade_builder/restrict_layout)), copyability (by [`support_copy`](https://ngcpp.github.io/proxy/spec/basic_facade_builder/support_copy)), relocatability (by [`support_relocation`](https://ngcpp.github.io/proxy/spec/basic_facade_builder/support_relocation)), and destructibility (by [`support_destruction`](https://ngcpp.github.io/proxy/spec/basic_facade_builder/support_destruction)).
-- **Reflection**: `proxy` supports type-based compile-time reflection for runtime queries. Please refer to [`facade_builder::add_reflection`](https://ngcpp.github.io/proxy/spec/basic_facade_builder/add_reflection) and [function template `proxy_reflect`](https://ngcpp.github.io/proxy/spec/proxy_reflect) for more details.
+- **Reflection**: `proxy` supports type-based compile-time reflection for runtime queries. Please refer to [`facade_builder::add_reflection`](https://ngcpp.github.io/proxy/spec/basic_facade_builder/add_reflection) and [function template `reflect`](https://ngcpp.github.io/proxy/spec/proxy_indirect_accessor/reflect) for more details.
 - **Non-owning proxy**: Although `proxy` can manage the lifetime of an object effectively, similar to a smart pointer, we sometimes want to dereference it before passing to a non-owning context. This has been implemented as an extension since 3.2.0. Please refer to [function template `make_proxy_view`](https://ngcpp.github.io/proxy/spec/make_proxy_view), [alias template `proxy_view`, class template `observer_facade`](https://ngcpp.github.io/proxy/spec/proxy_view) and [`skills::as_view`](https://ngcpp.github.io/proxy/spec/skills_as_view) for more details.
 - **RTTI**: [RTTI (run-time type information)](https://en.wikipedia.org/wiki/Run-time_type_information) provides "weak" reflection capability in C++ since the last century. Although it is not as powerful as reflection in some other languages (like `Object.GetType()` in C# or `Object.getClass()` in Java), it offers the basic infrastructure for type-safe casting at runtime. Since 4.0.0, "RTTI for `proxy`" has been implemented as an extension and allows users to opt-in for each facade definition. Please refer to [`skills::rtti`](https://ngcpp.github.io/proxy/spec/skills_rtti) for more details.
 - **Shared and weak ownership**: Although `proxy` can be created from a [`std::shared_ptr`](https://en.cppreference.com/w/cpp/memory/shared_ptr), extensions are available to create `proxy` objects with shared and weak ownership in a more efficient way since 3.3.0. Please refer to [function template `make_proxy_shared`](https://ngcpp.github.io/proxy/spec/make_proxy_shared), [`allocate_proxy_shared`](https://ngcpp.github.io/proxy/spec/allocate_proxy_shared), [alias template `weak_proxy`, class template `weak_facade`](https://ngcpp.github.io/proxy/spec/weak_proxy) and [`skills::as_weak`](https://ngcpp.github.io/proxy/spec/skills_as_weak) for more details.
@@ -243,7 +243,7 @@ Fetch via [CPM](https://github.com/cpm-cmake/CPM.cmake) (a thin wrapper over CMa
 ```cmake
 CPMAddPackage(
   NAME msft_proxy4
-  GIT_TAG 4.0.2
+  GIT_TAG 4.1.0
   GIT_REPOSITORY https://github.com/ngcpp/proxy.git
 )
 
@@ -259,7 +259,7 @@ Place a wrap file at `subprojects/proxy.wrap` and Meson will fetch the source au
 ```ini
 [wrap-git]
 url = https://github.com/ngcpp/proxy.git
-revision = 4.0.2
+revision = 4.1.0
 
 [provide]
 dependency_names = msft_proxy4

docs/spec/.pages

@@ -15,7 +15,7 @@ nav:
     - is_bitwise_trivially_relocatable: is_bitwise_trivially_relocatable.md
     - not_implemented: not_implemented.md
     - operator_dispatch: operator_dispatch
-    - proxy_indirect_accessor: proxy_indirect_accessor.md
+    - proxy_indirect_accessor: proxy_indirect_accessor
     - proxy_view<br />observer_facade: proxy_view.md
     - proxy: proxy
     - substitution_dispatch: substitution_dispatch

docs/spec/PRO_DEF_FREE_AS_MEM_DISPATCH.md

@@ -42,7 +42,7 @@ struct dispatch_name {
   template <class P, class D, class R, class... Args>
   struct accessor<P, D, R(Args...) cv ref noex> {
     R accessibility_func_name(Args... args) cv ref noex {
-      return pro::proxy_invoke<D, R(Args...) cv ref noex>(static_cast<P cv <ref ? ref : &>>(*this), std::forward<Args>(args)...);
+      return invoke<D, R(Args...) cv ref noex>(static_cast<P cv <ref ? ref : &>>(*this), std::forward<Args>(args)...);
     }
   };
 }

docs/spec/PRO_DEF_FREE_DISPATCH.md

@@ -39,7 +39,7 @@ struct dispatch_name {
   template <class P, class D, class R, class... Args>
   struct accessor<P, D, R(Args...) cv ref noex> {
     friend R accessibility_func_name(P cv <ref ? ref : &> self, Args... args) noex {
-      return pro::proxy_invoke<D, R(Args...) cv ref noex>(static_cast<P cv <ref ? ref : &>>(self), std::forward<Args>(args)...);
+      return invoke<D, R(Args...) cv ref noex>(static_cast<P cv <ref ? ref : &>>(self), std::forward<Args>(args)...);
     }
   };
 }

docs/spec/PRO_DEF_MEM_DISPATCH.md

@@ -41,7 +41,7 @@ struct dispatch_name {
   template <class P, class D, class R, class... Args>
   struct accessor<P, D, R(Args...) cv ref noex> {
     R accessibility_func_name(Args... args) cv ref noex {
-      return pro::proxy_invoke<D, R(Args...) cv ref noex>(static_cast<P cv <ref ? ref : &>>(*this), std::forward<Args>(args)...);
+      return invoke<D, R(Args...) cv ref noex>(static_cast<P cv <ref ? ref : &>>(*this), std::forward<Args>(args)...);
     }
   };
 }

docs/spec/ProAccessible.md

@@ -9,4 +9,4 @@ A type `T` meets the *ProAccessible* requirements of types `Args...` if the foll
 ## See Also
 
 - [class template `proxy`](proxy/README.md)
-- [class template `proxy_indirect_accessor`](proxy_indirect_accessor.md)
+- [class template `proxy_indirect_accessor`](proxy_indirect_accessor/README.md)

docs/spec/README.md

@@ -28,7 +28,7 @@ This document provides the API specifications for the C++ library Proxy (version
 | [`is_bitwise_trivially_relocatable`](is_bitwise_trivially_relocatable.md) | Specifies whether a type is bitwise trivially relocatable    |
 | [`not_implemented` ](not_implemented.md)                     | Exception thrown by `weak_dispatch` for the default implementation |
 | [`operator_dispatch`](operator_dispatch/README.md)           | Dispatch type for operator expressions with accessibility    |
-| [`proxy_indirect_accessor`](proxy_indirect_accessor.md)      | Provides indirection accessibility for `proxy`               |
+| [`proxy_indirect_accessor`](proxy_indirect_accessor/README.md) | Provides indirection accessibility for `proxy`               |
 | [`proxy_view`<br />`observer_facade`](proxy_view.md)         | Non-owning `proxy` optimized for raw pointer types           |
 | [`proxy`](proxy/README.md)                                   | Wraps a pointer object matching specified facade             |
 | [`substitution_dispatch`](substitution_dispatch/README.md)   | Dispatch type for `proxy` substitution with accessibility    |
@@ -55,8 +55,18 @@ This document provides the API specifications for the C++ library Proxy (version
 | [`make_proxy_shared`](make_proxy_shared.md)         | Creates a `proxy` object with shared ownership               |
 | [`make_proxy_view`](make_proxy_view.md)             | Creates a `proxy_view` object                                |
 | [`make_proxy`](make_proxy.md)                       | Creates a `proxy` object potentially with heap allocation    |
-| [`proxy_invoke`](proxy_invoke.md)                   | Invokes a `proxy` with a specified convention                |
-| [`proxy_reflect`](proxy_reflect.md)                 | Acquires reflection information of a contained type          |
+| [`proxy_invoke`](proxy_invoke.md)                   | (Deprecated since 4.1.0; use [`invoke`](proxy_indirect_accessor/invoke.md)) Invokes a `proxy` with a specified convention |
+| [`proxy_reflect`](proxy_reflect.md)                 | (Deprecated since 4.1.0; use [`reflect`](proxy_indirect_accessor/reflect.md)) Acquires reflection information of a contained type |
+
+### Non-Member Functions
+
+The following are not namespace-scope functions; each is a non-member function of [`proxy`](proxy/README.md) and [`proxy_indirect_accessor`](proxy_indirect_accessor/README.md), found only via [argument-dependent lookup](https://en.cppreference.com/w/cpp/language/adl). Each is documented separately for the two classes.
+
+| Name                 | For `proxy<F>`                                  | For `proxy_indirect_accessor<F>`                                  |
+| -------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
+| `invoke`             | [direct](proxy/invoke.md)                       | [indirect](proxy_indirect_accessor/invoke.md)                     |
+| `reflect`            | [direct](proxy/reflect.md)                      | [indirect](proxy_indirect_accessor/reflect.md)                    |
+| `reinterpret_invoke` | [direct](proxy/reinterpret_invoke.md)           | [indirect](proxy_indirect_accessor/reinterpret_invoke.md)         |
 
 ## Header `<proxy_macros.h>`
 

docs/spec/basic_facade_builder/.pages

@@ -1,6 +1,7 @@
 nav:
   - basic_facade_builder: README.md
   - add_convention<br />add_indirect_convention<br />add_direct_convention: add_convention.md
+  - add_facade_with_substitution: add_facade_with_substitution.md
   - add_facade: add_facade.md
   - add_reflection<br />add_indirect_reflection<br />add_direct_reflection: add_reflection.md
   - add_skill: add_skill.md