doc: Document FunctionTraits/ProxyMethodTraits classes

Author: ryanofsky

include/mp/proxy.h

@@ -144,12 +144,26 @@ struct ProxyServerCustom : public ProxyServerBase<Interface, Impl>
     using ProxyServerBase<Interface, Impl>::ProxyServerBase;
 };
 
-//! Function traits class used to get method parameter and result types in generated ProxyClient implementations from
-//! proxy-codegen.cpp.
+//! Function traits class used to get method parameter and result types, used in
+//! generated ProxyClient and ProxyServer classes produced by gen.cpp to get C++
+//! method type information. The generated code accesses these traits via
+//! intermediate ProxyClientMethodTraits and ProxyServerMethodTraits classes,
+//! which it is possible to specialize to change the way method arguments and
+//! return values are handled.
+//!
+//! Fields of the trait class are:
+//!
+//! Params   - TypeList of C++ ClassName::methodName parameter types
+//! Result   - Return type of ClassName::method
+//! Param<N> - helper to access individual parameters by index number.
+//! Fields   - helper alias that appends Result type to the Params typelist if
+//!            it not void.
 template <class Fn>
 struct FunctionTraits;
 
-//! Specialization of above to extract result and params types.
+//! Specialization of above extracting result and params types assuming the
+//! template argument is a pointer-to-method type,
+//! decltype(&ClassName::methodName)
 template <class _Class, class _Result, class... _Params>
 struct FunctionTraits<_Result (_Class::*const)(_Params...)>
 {
@@ -161,16 +175,20 @@ struct FunctionTraits<_Result (_Class::*const)(_Params...)>
         typename std::conditional<std::is_same<void, Result>::value, Params, TypeList<_Params..., _Result>>::type;
 };
 
-//! Traits class for a method specialized by method parameters.
+//! Traits class for a proxy method, providing the same
+//! Params/Result/Param/Fields described in the FunctionTraits class above, plus
+//! an additional invoke() method that calls the C++ method which is being
+//! proxied, forwarding any arguments.
 //!
-//! Param and Result typedefs can be customized to adjust parameter and return types on client side.
+//! The template argument should be the InterfaceName::MethodNameParams class
+//! (generated by Cap'n Proto) associated with the method.
 //!
-//! Invoke method customized to adjust parameter and return types on server side.
-//!
-//! Normal method calls go through the ProxyMethodTraits struct specialization
-//! below, not this default struct, which is only used if there is no
-//! ProxyMethod::impl method pointer, which is only true for construct/destroy
-//! methods.
+//! Note: The class definition here is just the fallback definition used when
+//! the other specialization below doesn't match. The fallback is only used for
+//! capnp methods which do not have corresponding C++ methods, which in practice
+//! is just the two special construct() and destroy() methods described in \ref
+//! ProxyClientBase. These methods don't have any C++ parameters or return
+//! types, so the trait information below reflects that.
 template <typename MethodParams, typename Enable = void>
 struct ProxyMethodTraits
 {
@@ -184,7 +202,18 @@ struct ProxyMethodTraits
     }
 };
 
-//! Specialization of above.
+//! Specialization of above for proxy methods that have a
+//! ProxyMethod<InterfaceName::MethodNameParams>::impl pointer-to-method
+//! constant defined by generated code. This includes all functions defined in
+//! the capnp interface except any construct() or destroy() methods, that are
+//! assumed not to correspond to real member functions in the C++ class, and
+//! will use the fallback traits definition above. The generated code this
+//! specialization relies on looks like:
+//!
+//! struct ProxyMethod<InterfaceName::MethodNameParams>
+//! {
+//!     static constexpr auto impl = &ClassName::methodName;
+//! };
 template <typename MethodParams>
 struct ProxyMethodTraits<MethodParams, Require<decltype(ProxyMethod<MethodParams>::impl)>>
     : public FunctionTraits<decltype(ProxyMethod<MethodParams>::impl)>