Add a bunch of more docs on the fn namespace

sus/fn/fn.h

@@ -18,3 +18,75 @@
 #include "sus/fn/fn_concepts.h"
 #include "sus/fn/fn_dyn.h"
 // IWYU pragma: end_exports
+
+namespace sus {
+
+/// The [`Fn`]($sus::fn::Fn), [`FnMut`]($sus::fn::FnMut) and
+/// [`FnOnce`]($sus::fn::FnOnce) concepts for working with functors
+/// and callable types.
+///
+/// There are three main concepts that model anything callable:
+/// * A [`Fn`]($sus::fn::Fn) represents a callable type which is const and will
+///   return the same outputs given the same inputs.
+/// * A [`FnMut`]($sus::fn::FnMut) represents a callable type which is allowed
+///   to generate unique outputs on each call. This is the most commonly used
+///   of the three.
+/// * A [`FnOnce`]($sus::fn::FnOnce) represents a callable type which will only
+///   be called once.
+///
+/// As these are concepts, not concrete types, they can not enforce any
+/// behaviour but rather represent a protocol of expectations. Types designed to
+/// satisfy these concepts should adhere to them, and safely handle misuse, such
+/// as panicking (via [`panic`]($sus::assertions::panic)) if called twice
+/// when it is not supported.
+///
+/// To make a type satisfy [`Fn`]($sus::fn::Fn) it should have a
+/// const call `operator()`, to safisfy [`FnMut`]($sus::fn::FnMut) it
+/// should have a mutable call `operator()` and to satisfy
+/// [`FnOnce`]($sus::fn::FnOnce), it should have an
+/// rvalue-qualfied call `operator()`.
+///
+/// A [`Fn`]($sus::fn::Fn) type will also satisfy the other two, since a const
+/// function that chooses not to mutate, or that is called only once, does not
+/// violate the protocol.
+///
+/// Similarly, a [`FnMut`]($sus::fn::FnMut) type will also satisfy
+/// [`FnOnce`]($sus::fn::FnOnce) as it is valid to only call it a single time.
+///
+/// The `fn` namespace provides matchers for use in the function concepts to
+/// match against and constrain the return type of a function.
+/// * [`NonVoid`]($sus::fn::NonVoid) will match function types that return
+///   a type other than void.
+/// * [`Anything`]($sus::fn::Anything) will match function types that return
+///   any type.
+///
+/// An example of using [`NonVoid`]($sus::fn::NonVoid) to match the return
+/// type of a [`FnMut`]($sus::fn::FnMut):
+/// ```
+/// // Accepts a function that can be called repeatedly with `i32` and which
+/// // returns something other than void. A void type would break compilation
+/// // as it can not be assigned to a variable, so it rejects functions with a
+/// // void return type.
+/// auto func = [](FnMut<NonVoid(i32)> auto f) {
+///   auto x = f(0);
+///   x += 3;
+/// };
+/// func([](i32) { return 3; });
+/// ```
+///
+/// The same with [`FnMut`]($sus::fn::FnMut)
+/// [type-erased]($sus::boxed::DynConcept) as [`DynFnMut`](
+/// $(sus::fn::DynFnMut) to avoid templates. The full type must be specified
+/// when not working with templates, so [`NonVoid`]($sus::fn::NonVoid) can
+/// not be used.
+/// ```
+/// auto func = [](DynFnMut<i32(i32)>& f) {
+///   auto x = f(0);
+///   x += 3;
+/// };
+///
+/// func(sus::dyn<DynFnMut<i32(i32)>>([](i32) { return 3; }));
+/// ```
+namespace fn {}
+
+}  // namespace sus

sus/fn/fn_concepts.h

@@ -87,6 +87,24 @@ struct Anything {
 /// Undefined Behaviour depending on the type that is being used to satisfy
 /// `FnOnce`.
 ///
+/// # Type erasure
+///
+/// Using a concept like `FnOnce` in a function parameter requires the function
+/// to be a template. Template functions can not be virtual, they must appear
+/// in the header, and they can have a negative impact on binary size. So it can
+/// be desirable to work with a `FnOnce` without templates.
+///
+/// To do so, `FnOnce` supports being type-erased, on the heap or the stack,
+/// into a [`DynFnOnce`]($sus::fn::DynFnOnce) type.
+/// To receive ownership of a type-erased `FnOnce`, receive a
+/// [`Box`]($sus::boxed::Box)`<`[`DynFnOnce<R(Args...)>`]($sus::fn::DynFnOnce)`>`
+/// instead.
+/// To receive a reference to a type-erased `FnOnce`, receive a
+/// [`DynFnOnce<R(Args...)>&&`]($sus::fn::DynFnOnce) instead.
+///
+/// See [`DynConcept`]($sus::boxed::DynConcept) for more on type erasure of
+/// concept-satisfying types.
+///
 /// # Compatibility
 /// Any callable type that satisfies `Fn` or `FnMut` will also satisfy `FnOnce`.
 /// While a `FnOnce` should only be called once, this is compatible with the
@@ -187,6 +205,24 @@ concept FnOnce = requires {
 /// A `FnMut` may be called any number of times, unlike `FnOnce`,
 /// and should not be moved when called.
 ///
+/// # Type erasure
+///
+/// Using a concept like `FnMut` in a function parameter requires the function
+/// to be a template. Template functions can not be virtual, they must appear
+/// in the header, and they can have a negative impact on binary size. So it can
+/// be desirable to work with a `FnMut` without templates.
+///
+/// To do so, `FnMut` supports being type-erased, on the heap or the stack,
+/// into a [`DynFnMut`]($sus::fn::DynFnMut) type.
+/// To receive ownership of a type-erased `FnMut`, receive a
+/// [`Box`]($sus::boxed::Box)`<`[`DynFnMut<R(Args...)>`]($sus::fn::DynFnMut)`>`
+/// instead.
+/// To receive a reference to a type-erased `FnMut`, receive a
+/// [`DynFnMut<R(Args...)>&&`]($sus::fn::DynFnMut) instead.
+///
+/// See [`DynConcept`]($sus::boxed::DynConcept) for more on type erasure of
+/// concept-satisfying types.
+///
 /// # Compatibility
 /// Any callable type that satisfies `Fn` or `FnMut` will also satisfy `FnOnce`.
 /// While a `FnOnce` should only be called once, this is compatible with the
@@ -292,6 +328,24 @@ concept FnMut = requires {
 /// A `Fn` may be called any number of times, unlike `FnOnce`, and should not
 /// be moved when called.
 ///
+/// # Type erasure
+///
+/// Using a concept like `Fn` in a function parameter requires the function
+/// to be a template. Template functions can not be virtual, they must appear
+/// in the header, and they can have a negative impact on binary size. So it can
+/// be desirable to work with a `Fn` without templates.
+///
+/// To do so, `Fn` supports being type-erased, on the heap or the stack,
+/// into a [`DynFn`]($sus::fn::DynFn) type.
+/// To receive ownership of a type-erased `Fn`, receive a
+/// [`Box`]($sus::boxed::Box)`<`[`DynFn<R(Args...)>`]($sus::fn::DynFn)`>`
+/// instead.
+/// To receive a reference to a type-erased `Fn`, receive a
+/// [`DynFn<R(Args...)>&&`]($sus::fn::DynFn) instead.
+///
+/// See [`DynConcept`]($sus::boxed::DynConcept) for more on type erasure of
+/// concept-satisfying types.
+///
 /// # Compatibility
 /// Any callable type that satisfies `Fn` will also satisfy `FnMut` and
 /// `FnOnce`. A `Fn` may be called multiple times, or a single time, which is

sus/fn/fn_concepts_unittest.cc

@@ -471,4 +471,16 @@ TEST(FnConcepts, Example_Method) {
   sus::check(o.map(&Class::value) == sus::some(42));
 }
 
+TEST(Fn, Example_NonVoid) {
+  // Accepts a function that can be called repeatedly with `i32` and which
+  // returns something other than void. A void type would break compilation
+  // as it can not be assigned to a variable, so it rejects functions with a
+  // void return type.
+  auto func = [](FnMut<NonVoid(i32)> auto f) {
+    auto x = f(0);
+    x += 3;
+  };
+  func([](i32) { return 3; });
+}
+
 }  // namespace

sus/fn/fn_dyn_unittest.cc

@@ -77,4 +77,13 @@ TEST(FnOnceDyn, FnOnceBox) {
   EXPECT_EQ(d, 1 * 2);
 }
 
+TEST(Fn, Example_NonVoidDyn) {
+  auto func = [](DynFnMut<i32(i32)>& f) {
+    auto x = f(0);
+    x += 3;
+  };
+
+  func(sus::dyn<DynFnMut<i32(i32)>>([](i32) { return 3; }));
+}
+
 }  // namespace