Add semantic documentation

boostorg · Sep 28, 2015 · 2296dbe · 2296dbe
1 parent e8dc67d
commit 2296dbe
Show file tree

Hide file tree

Showing 20 changed files with 111 additions and 0 deletions.
diff --git a/doc/src/overview.md b/doc/src/overview.md
@@ -29,3 +29,13 @@ A decorator is a function that returns a function adaptor. The function adaptor
 template<class... Ts>
 FunctionAdaptor Decorator(Ts...);
 ```
+
+Semantics
+---------
+
+Some parts of the documentation provides the meaning(or equivalence) of an expression. Here is a guide of thos symbols:
+
+* `f`, `g`, `fs`, `gs`, `p` are functions
+* `x`, `y`, `xs`, `xs` are parameters to a function
+* `T` represents some type
+* `...` are parameter packs 
diff --git a/fit/always.h b/fit/always.h
@@ -31,6 +31,11 @@
 ///     template<class T>
 ///     constexpr /* unspecified */ always_ref(T& value);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(always(x)(xs...) == x);
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/apply.h b/fit/apply.h
@@ -22,6 +22,11 @@
 ///     template<class F, class... Ts>
 ///     constexpr auto apply(F&& f, Ts&&... xs);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(apply(f)(xs...) == f(xs...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/apply_eval.h b/fit/apply_eval.h
@@ -23,6 +23,11 @@
 ///     template<class F, class... Ts>
 ///     constexpr auto apply_eval(F&& f, Ts&&... xs);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(apply_eval(f)(xs...) == f(eval(xs)...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/by.h b/fit/by.h
@@ -33,6 +33,11 @@
 ///     template<class Projection>
 ///     constexpr by_adaptor<Projection> by(Projection p);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(by(p, f)(xs...) == f(p(xs)...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/capture.h b/fit/capture.h
@@ -41,6 +41,11 @@
 ///     template<class... Ts>
 ///     constexpr auto capture_decay(Ts&&... xs);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(capture(xs...)(f)(ys...) == f(xs..., ys...));
+/// 
 /// 
 /// Example
 /// -------

diff --git a/fit/combine.h b/fit/combine.h
@@ -24,6 +24,11 @@
 ///     template<class F, class... Gs>
 ///     constexpr combine_adaptor<F, Gs...> combine(F f, Gs... gs);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(combine(f, gs...)(xs...) == f(gs(xs)...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/compose.h b/fit/compose.h
@@ -26,6 +26,11 @@
 ///     template<class... Fs>
 ///     constexpr compose_adaptor<Fs...> compose(Fs... fs);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(compose(f, g)(xs...) == f(g(xs...)));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/compress.h b/fit/compress.h
@@ -31,6 +31,14 @@
 ///     template<class F>
 ///     constexpr compress_adaptor<F> compress(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(compress(f, z)() == z);
+///     assert(compress(f, z)(x, xs...) == compress(f, f(z, x))(xs...));
+///     assert(compress(f)(x) == x);
+///     assert(compress(f)(x, y, xs...) == compress(f)(f(x, y), xs...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/construct.h b/fit/construct.h
@@ -27,6 +27,11 @@
 ///     template<template<class...> class Template>
 ///     constexpr auto construct();
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(construct<T>()(xs...) == T(xs...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/decorate.h b/fit/decorate.h
@@ -22,6 +22,11 @@
 ///     template<class F>
 ///     constexpr decorate_adaptor<F> decorate(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(decorate(f)(x)(g)(xs...) == f(x, g, xs...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/fix.h b/fit/fix.h
@@ -27,6 +27,11 @@
 ///     template<class F>
 ///     constexpr fix_adaptor<F> fix(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(fix(f)(xs...) == f(f, xs...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/flip.h b/fit/flip.h
@@ -22,6 +22,11 @@
 ///     template<class F>
 ///     flip_adaptor<F> flip(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(flip(f)(x, y, xs...) == f(y, x, xs...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/flow.h b/fit/flow.h
@@ -26,6 +26,11 @@
 ///     template<class... Fs>
 ///     constexpr flow_adaptor<Fs...> flow(Fs... fs);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(flow(f, g)(xs...) == g(f(xs...)));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/identity.h b/fit/identity.h
@@ -16,6 +16,11 @@
 /// 
 /// The `identity` function is a unary function object that returns whats given to it. 
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(idenity(x) == x);
+/// 
 /// Synopsis
 /// --------
 /// 

diff --git a/fit/infix.h b/fit/infix.h
@@ -24,6 +24,11 @@
 ///     template<class F>
 ///     constexpr infix_adaptor<F> infix(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert((x <infix(f)> y) == f(x, y));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/partial.h b/fit/partial.h
@@ -27,6 +27,11 @@
 ///     template<class F>
 ///     constexpr partial_adaptor<F> partial(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(partial(f)(xs...)(ys...) == f(xs..., ys...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/pipable.h b/fit/pipable.h
@@ -26,6 +26,11 @@
 ///     template<class F>
 ///     constexpr pipable_adaptor<F> pipable(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(x | pipable(f)(ys...) == f(x, ys...));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/reverse_compress.h b/fit/reverse_compress.h
@@ -32,6 +32,14 @@
 ///     template<class F>
 ///     constexpr reverse_compress_adaptor<F> reverse_compress(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(reverse_compress(f, z)() == z);
+///     assert(reverse_compress(f, z)(x, xs...) == f(reverse_compress(f, z)(xs...), x));
+///     assert(reverse_compress(f)(x) == x);
+///     assert(reverse_compress(f)(x, xs...) == f(reverse_compress(f)(xs...), x));
+/// 
 /// Requirements
 /// ------------
 /// 

diff --git a/fit/rotate.h b/fit/rotate.h
@@ -23,6 +23,11 @@
 ///     template<class F>
 ///     rotate_adaptor<F> rotate(F f);
 /// 
+/// Semantics
+/// ---------
+/// 
+///     assert(rotate(f)(x, xs...) == f(xs..., x));
+/// 
 /// Requirements
 /// ------------
 ///