diff --git a/CMakeLists.txt b/CMakeLists.txt
index 74d28d5b..9e51cb19 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -2,10 +2,31 @@
 # Distributed under the Boost Software License, Version 1.0.
 # See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt
 
-cmake_minimum_required(VERSION 2.8.12)
+cmake_minimum_required(VERSION 3.0)
 
 project(Metal CXX)
 
+set(METAL_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include/")
+
+file(STRINGS "${METAL_INCLUDE_DIR}/metal/config/version.hpp"
+    METAL_CONFIG_VERSION_HPP REGEX "METAL_[A-Z]+ [0-9]+" LIMIT_COUNT 3
+)
+
+LIST(GET METAL_CONFIG_VERSION_HPP 0 METAL_MAJOR)
+LIST(GET METAL_CONFIG_VERSION_HPP 1 METAL_MINOR)
+LIST(GET METAL_CONFIG_VERSION_HPP 2 METAL_PATCH)
+
+string(REGEX REPLACE ".*MAJOR ([0-9]+).*" "\\1" METAL_MAJOR "${METAL_MAJOR}")
+string(REGEX REPLACE ".*MINOR ([0-9]+).*" "\\1" METAL_MINOR "${METAL_MINOR}")
+string(REGEX REPLACE ".*PATCH ([0-9]+).*" "\\1" METAL_PATCH "${METAL_PATCH}")
+
+set(METAL_VERSION "${METAL_MAJOR}.${METAL_MINOR}.${METAL_PATCH}")
+
+message(STATUS "Configuring Metal ${METAL_VERSION}")
+
+add_library(metal INTERFACE)
+target_include_directories(metal INTERFACE ${METAL_INCLUDE_DIR})
+
 include("${CMAKE_SOURCE_DIR}/cmake/config.cmake")
 include("${CMAKE_SOURCE_DIR}/cmake/testing.cmake")
 include("${CMAKE_SOURCE_DIR}/cmake/deployment.cmake")
diff --git a/cmake/config.cmake b/cmake/config.cmake
index 1c46c21c..5e99d9ef 100644
--- a/cmake/config.cmake
+++ b/cmake/config.cmake
@@ -2,24 +2,6 @@
 # Distributed under the Boost Software License, Version 1.0.
 # See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt
 
-set(METAL_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include/")
-
-file(STRINGS "${METAL_INCLUDE_DIR}/metal/config/version.hpp"
-    METAL_CONFIG_VERSION_HPP REGEX "METAL_[A-Z]+ [0-9]+" LIMIT_COUNT 3
-)
-
-LIST(GET METAL_CONFIG_VERSION_HPP 0 METAL_MAJOR)
-LIST(GET METAL_CONFIG_VERSION_HPP 1 METAL_MINOR)
-LIST(GET METAL_CONFIG_VERSION_HPP 2 METAL_PATCH)
-
-string(REGEX REPLACE ".*MAJOR ([0-9]+).*" "\\1" METAL_MAJOR "${METAL_MAJOR}")
-string(REGEX REPLACE ".*MINOR ([0-9]+).*" "\\1" METAL_MINOR "${METAL_MINOR}")
-string(REGEX REPLACE ".*PATCH ([0-9]+).*" "\\1" METAL_PATCH "${METAL_PATCH}")
-
-set(METAL_VERSION "${METAL_MAJOR}.${METAL_MINOR}.${METAL_PATCH}")
-
-message(STATUS "Configuring Metal ${METAL_VERSION}")
-
 option(METAL_ENABLE_WARNINGS        "enable compiler warnings"               ON)
 option(METAL_STRICT                 "treat compiler warnings as errors"     OFF)
 option(METAL_VERBOSE                "increase output verbosity"             OFF)
diff --git a/cmake/deployment.cmake b/cmake/deployment.cmake
index 3f4a13e7..3620f181 100644
--- a/cmake/deployment.cmake
+++ b/cmake/deployment.cmake
@@ -25,7 +25,7 @@ foreach(_ INCLUDE CMAKE)
 endforeach()
 
 file(RELATIVE_PATH METAL_INCLUDE_DIRS
-    "${METAL_CMAKE_INSTALL_DIR}" "${METAL_INCLUDE_INSTALL_DIR}"
+    ${METAL_CMAKE_INSTALL_DIR} ${METAL_INCLUDE_INSTALL_DIR}
 )
 
 set(METAL_INCLUDE_DIRS "\${METAL_CMAKE_DIR}/${METAL_INCLUDE_DIRS}")
@@ -40,13 +40,10 @@ configure_file(cmake/MetalConfigVersion.cmake.in
     @ONLY
 )
 
-install(DIRECTORY
-    "${METAL_INCLUDE_DIR}"
-    DESTINATION "${METAL_INCLUDE_INSTALL_DIR}"
-)
+install(DIRECTORY ${METAL_INCLUDE_DIR} DESTINATION ${METAL_INCLUDE_INSTALL_DIR})
 
 install(FILES
     "${PROJECT_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/MetalConfig.cmake"
     "${PROJECT_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/MetalConfigVersion.cmake"
-    DESTINATION "${METAL_CMAKE_INSTALL_DIR}"
+    DESTINATION ${METAL_CMAKE_INSTALL_DIR}
 )
diff --git a/cmake/testing.cmake b/cmake/testing.cmake
index a084e9b1..4843001d 100644
--- a/cmake/testing.cmake
+++ b/cmake/testing.cmake
@@ -30,6 +30,7 @@ function(metal_build_test_tree _root _prefix)
         set(target ${_root}.${node})
         if(EXISTS "${_prefix}/${node}.cpp")
             add_executable(${target} EXCLUDE_FROM_ALL "${_prefix}/${node}.cpp")
+            target_link_libraries(${target} metal)
         else()
             add_custom_target(${target})
         endif()
diff --git a/doc/js/metal.js b/doc/js/metal.js
index 87e1d55d..a4563a87 100644
--- a/doc/js/metal.js
+++ b/doc/js/metal.js
@@ -3,12 +3,13 @@
 // See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt
 
 $(function(){
-    var page = window.location.pathname.split("/").pop().split("#")[0];
+    var page = window.location.pathname.split("/").pop();
+    if(!page.length)
+        page = "index.html";
 
-    if(/[^_]+__[^_.]+.html/.test(page))
+    var section = page;
+    if(/[^_]+__[^_.]+.html/.test(section))
         section = "modules.html";
-    else
-        section = page;
 
     $("#sections > #menu a[href='" + section +"']").each(function(){
         $(this).parent().addClass("active");
diff --git a/doc/manual.md b/doc/manual.md
index c86f10e9..97d080e0 100644
--- a/doc/manual.md
+++ b/doc/manual.md
@@ -94,7 +94,7 @@ Metal may optionally be installed system-wide to ease integration with external
 projects. If you'd rather use Metal locally, you may skip to the
 [next section](#using_metal).
 
-Make sure to have [CMake] v2.8.12 or newer installed on your system, then,
+Make sure to have [CMake] v3.0 or newer installed on your system, then,
 from within an empty directory, issue the following commands.
 
     cmake /path/to/Metal
diff --git a/example/CMakeLists.txt b/example/CMakeLists.txt
index 186b7b70..3978baca 100644
--- a/example/CMakeLists.txt
+++ b/example/CMakeLists.txt
@@ -2,7 +2,6 @@
 # Distributed under the Boost Software License, Version 1.0.
 # See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt
 
-include_directories("${METAL_INCLUDE_DIR}")
 include_directories("${CMAKE_CURRENT_SOURCE_DIR}/include/")
 
 add_custom_target(examples)
diff --git a/example/src/list.cpp b/example/src/list.cpp
index 16fa1d12..13d6585b 100644
--- a/example/src/list.cpp
+++ b/example/src/list.cpp
@@ -4,6 +4,8 @@
 
 #include <metal.hpp>
 
+#include <cstdint>
+
 #include "example.hpp"
 
 HIDE(
@@ -21,3 +23,608 @@ using l = metal::list<int, int*, int&>;
 
 IS_SAME(metal::is_list<l>, metal::true_);
 )
+
+HIDE(
+/// [is_list]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::is_list<l>, metal::true_);
+IS_SAME(metal::is_list<metal::list<>>, metal::true_);
+IS_SAME(metal::is_list<metal::pair<int, int*>>, metal::true_);
+IS_SAME(metal::is_list<metal::map<metal::pair<int, int*>>>, metal::true_);
+/// [is_list]
+)
+
+HIDE(
+/// [size]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::size<l>, metal::number<6>);
+IS_SAME(metal::size<metal::list<>>, metal::number<0>);
+/// [size]
+)
+
+HIDE(
+/// [empty]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::empty<l>, metal::false_);
+IS_SAME(metal::empty<metal::list<>>, metal::true_);
+/// [empty]
+)
+
+HIDE(
+/// [indices]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::indices<l>,
+    metal::list<
+        metal::number<0>, metal::number<1>, metal::number<2>,
+        metal::number<3>, metal::number<4>, metal::number<5>
+    >
+);
+/// [indices]
+)
+
+HIDE(
+/// [at]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::at<l, metal::number<0>>, short);
+IS_SAME(metal::at<l, metal::number<1>>, int);
+IS_SAME(metal::at<l, metal::number<2>>, long);
+IS_SAME(metal::at<l, metal::number<3>>, float);
+IS_SAME(metal::at<l, metal::number<4>>, double);
+IS_SAME(metal::at<l, metal::number<5>>, void);
+/// [at]
+)
+
+HIDE(
+/// [front]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::front<l>, short);
+/// [front]
+)
+
+HIDE(
+/// [back]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::back<l>, void);
+/// [back]
+)
+
+HIDE(
+/// [contains]
+using l = metal::list<int, int, float, int, void, float>;
+
+IS_SAME(metal::contains<l, int>, metal::true_);
+IS_SAME(metal::contains<l, float>, metal::true_);
+IS_SAME(metal::contains<l, void>, metal::true_);
+IS_SAME(metal::contains<l, char>, metal::false_);
+/// [contains]
+)
+
+HIDE(
+/// [count]
+using l = metal::list<int, int, float, int, void, float>;
+
+IS_SAME(metal::count<l, int>, metal::number<3>);
+IS_SAME(metal::count<l, float>, metal::number<2>);
+IS_SAME(metal::count<l, void>, metal::number<1>);
+IS_SAME(metal::count<l, char>, metal::number<0>);
+/// [count]
+)
+
+HIDE(
+/// [find]
+using l = metal::list<int, int, float, int, void, float>;
+
+IS_SAME(metal::find<l, int>, metal::number<0>);
+IS_SAME(metal::find<l, float>, metal::number<2>);
+IS_SAME(metal::find<l, void>, metal::number<4>);
+IS_SAME(metal::find<l, char>, metal::number<6>);
+/// [find]
+)
+
+HIDE(
+/// [copy]
+using l = metal::list<int, int, float, int, void, float>;
+
+IS_SAME(metal::copy<l, int>, metal::list<int, int, int>);
+IS_SAME(metal::copy<l, float>, metal::list<float, float>);
+IS_SAME(metal::copy<l, void>, metal::list<void>);
+IS_SAME(metal::copy<l, char>, metal::list<>);
+/// [copy]
+)
+
+HIDE(
+/// [remove]
+using l = metal::list<int, int, float, int, void, float>;
+
+IS_SAME(metal::remove<l, int>, metal::list<float, void, float>);
+IS_SAME(metal::remove<l, float>, metal::list<int, int, int, void>);
+IS_SAME(metal::remove<l, void>, metal::list<int, int, float, int, float>);
+IS_SAME(metal::remove<l, char>, metal::list<int, int, float, int, void, float>);
+/// [remove]
+)
+
+HIDE(
+/// [replace]
+using l = metal::list<int, int, float, int, void, float>;
+
+IS_SAME(
+    metal::replace<l, int, char>,
+    metal::list<char, char, float, char, void, float>
+);
+
+IS_SAME(
+    metal::replace<l, float, char>,
+    metal::list<int, int, char, int, void, char>
+);
+
+IS_SAME(
+    metal::replace<l, void, char>,
+    metal::list<int, int, float, int, char, float>
+);
+
+IS_SAME(
+    metal::replace<l, char, char>,
+    metal::list<int, int, float, int, void, float>
+);
+/// [replace]
+)
+
+HIDE(
+/// [all]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::all<l, metal::lambda<is_fundamental>>, metal::true_);
+IS_SAME(metal::all<l, metal::lambda<is_floating_point>>, metal::false_);
+IS_SAME(metal::all<l, metal::lambda<is_class>>, metal::false_);
+/// [all]
+)
+
+HIDE(
+/// [any]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::any<l, metal::lambda<is_fundamental>>, metal::true_);
+IS_SAME(metal::any<l, metal::lambda<is_floating_point>>, metal::true_);
+IS_SAME(metal::any<l, metal::lambda<is_class>>, metal::false_);
+/// [any]
+)
+
+HIDE(
+/// [none]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::none<l, metal::lambda<is_fundamental>>, metal::false_);
+IS_SAME(metal::none<l, metal::lambda<is_floating_point>>, metal::false_);
+IS_SAME(metal::none<l, metal::lambda<is_class>>, metal::true_);
+/// [none]
+)
+
+HIDE(
+/// [count_if]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::count_if<l, metal::lambda<is_fundamental>>, metal::number<6>);
+IS_SAME(metal::count_if<l, metal::lambda<is_floating_point>>, metal::number<2>);
+IS_SAME(metal::count_if<l, metal::lambda<is_class>>, metal::number<0>);
+/// [count_if]
+)
+
+HIDE(
+/// [find_if]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::find_if<l, metal::lambda<is_fundamental>>, metal::number<0>);
+IS_SAME(metal::find_if<l, metal::lambda<is_floating_point>>, metal::number<3>);
+IS_SAME(metal::find_if<l, metal::lambda<is_class>>, metal::number<6>);
+/// [find_if]
+)
+
+HIDE(
+/// [partition]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::partition<l, metal::lambda<is_fundamental>>,
+    metal::pair<
+        metal::list<short, int, long, float, double, void>,
+        metal::list<>
+    >
+);
+
+IS_SAME(
+    metal::partition<l, metal::lambda<is_floating_point>>,
+    metal::pair<
+        metal::list<float, double>,
+        metal::list<short, int, long, void>
+    >
+);
+
+IS_SAME(
+    metal::partition<l, metal::lambda<is_class>>,
+    metal::pair<
+        metal::list<>,
+        metal::list<short, int, long, float, double, void>
+    >
+);
+/// [partition]
+)
+
+HIDE(
+/// [copy_if]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::copy_if<l, metal::lambda<is_fundamental>>,
+    metal::list<short, int, long, float, double, void>
+);
+
+IS_SAME(
+    metal::copy_if<l, metal::lambda<is_floating_point>>,
+    metal::list<float, double>
+);
+
+IS_SAME(metal::copy_if<l, metal::lambda<is_class>>, metal::list<>);
+/// [copy_if]
+)
+
+HIDE(
+/// [remove_if]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::remove_if<l, metal::lambda<is_fundamental>>, metal::list<>);
+
+IS_SAME(
+    metal::remove_if<l, metal::lambda<is_floating_point>>,
+    metal::list<short, int, long, void>
+);
+
+IS_SAME(
+    metal::remove_if<l, metal::lambda<is_class>>,
+    metal::list<short, int, long, float, double, void>
+);
+/// [remove_if]
+)
+
+HIDE(
+/// [replace_if]
+template<typename val>
+using is_fundamental =
+    metal::same<typename std::is_fundamental<val>::type, std::true_type>;
+
+template<typename val>
+using is_floating_point =
+    metal::same<typename std::is_floating_point<val>::type, std::true_type>;
+
+template<typename val>
+using is_class = metal::same<typename std::is_class<val>::type, std::true_type>;
+
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::replace_if<l, metal::lambda<is_fundamental>, char>,
+    metal::list<char, char, char, char, char, char>
+);
+
+IS_SAME(
+    metal::replace_if<l, metal::lambda<is_floating_point>, char>,
+    metal::list<short, int, long, char, char, void>
+);
+
+IS_SAME(
+    metal::replace_if<l, metal::lambda<is_class>, char>,
+    metal::list<short, int, long, float, double, void>
+);
+/// [replace_if]
+)
+
+HIDE(
+/// [flatten]
+using character = metal::list<char, wchar_t, char16_t, char32_t>;
+using integral = metal::list<short, int, long, long long>;
+using floating = metal::list<float, double, long double>;
+
+IS_SAME(
+    metal::flatten<metal::list<character, metal::list<integral, floating>>>,
+    metal::list<
+        char, wchar_t, char16_t, char32_t,
+        short, int, long, long long,
+        float, double, long double
+    >
+);
+/// [flatten]
+)
+
+HIDE(
+/// [join]
+using character = metal::list<char, wchar_t, char16_t, char32_t>;
+using integral = metal::list<short, int, long, long long>;
+using floating = metal::list<float, double, long double>;
+
+IS_SAME(
+    metal::join<character, integral, floating>,
+    metal::list<
+        char, wchar_t, char16_t, char32_t,
+        short, int, long, long long,
+        float, double, long double
+    >
+);
+/// [join]
+)
+
+HIDE(
+/// [splice]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::splice<l, metal::number<2>, metal::list<char, char[]>>,
+    metal::list<short, int, char, char[], long, float, double, void>
+);
+/// [splice]
+)
+
+HIDE(
+/// [insert]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::insert<l, metal::number<2>, unsigned>,
+    metal::list<short, int, unsigned, long, float, double, void>
+);
+/// [insert]
+)
+
+HIDE(
+/// [append]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::append<l, char, char[]>,
+    metal::list<short, int, long, float, double, void, char, char[]>
+);
+/// [append]
+)
+
+HIDE(
+/// [prepend]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::prepend<l, char, char[]>,
+    metal::list<char, char[], short, int, long, float, double, void>
+);
+/// [prepend]
+)
+
+HIDE(
+/// [range]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::range<l, metal::number<2>, metal::number<5>>,
+    metal::list<long, float, double>
+);
+
+IS_SAME(
+    metal::range<l, metal::number<5>, metal::number<2>>,
+    metal::list<double, float, long>
+);
+/// [range]
+)
+
+HIDE(
+/// [erase]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::erase<l, metal::number<2>, metal::number<5>>,
+    metal::list<short, int, void>
+);
+
+IS_SAME(
+    metal::erase<l, metal::number<5>, metal::number<2>>,
+    metal::list<short, int, void>
+);
+/// [erase]
+)
+
+HIDE(
+/// [drop]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::drop<l, metal::number<3>>, metal::list<float, double, void>);
+/// [drop]
+)
+
+HIDE(
+/// [take]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::take<l, metal::number<3>>, metal::list<short, int, long>);
+/// [take]
+)
+
+HIDE(
+/// [reverse]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(metal::reverse<l>, metal::list<void, double, float, long, int, short>);
+/// [reverse]
+)
+
+HIDE(
+/// [rotate]
+using l = metal::list<short, int, long, float, double, void>;
+
+IS_SAME(
+    metal::rotate<l, metal::number<2>>,
+    metal::list<long, float, double, void, short, int>
+);
+
+IS_SAME(
+    metal::rotate<l, metal::number<-2>>,
+    metal::list<double, void, short, int, long, float>
+);
+/// [rotate]
+)
+
+HIDE(
+/// [sort]
+using l = metal::list<int16_t, int8_t, uint16_t, int32_t, uint32_t, uint8_t>;
+
+template<typename x, typename y> // strict ordering
+using smaller = metal::number<sizeof(x) < sizeof(y)>;
+
+IS_SAME(
+    metal::sort<l, metal::lambda<smaller>>, // stable sorting
+    metal::list<int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t>
+);
+
+template<typename x, typename y> // partial ordering
+using not_bigger = metal::number<sizeof(x) <= sizeof(y)>;
+
+IS_SAME(
+    metal::sort<l, metal::lambda<not_bigger>>, // non-stable sorting
+    metal::list<uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t>
+);
+/// [sort]
+)
+
+HIDE(
+/// [transpose]
+using l = metal::list<
+    metal::list<int, int&, int*, int[]>,
+    metal::list<char, char&, char*, char[]>,
+    metal::list<float, float&, float*, float[]>
+>;
+
+IS_SAME(
+    metal::transpose<l>,
+    metal::list<
+        metal::list<int, char, float>,
+        metal::list<int&, char&, float&>,
+        metal::list<int*, char*, float*>,
+        metal::list<int[], char[], float[]>
+    >
+);
+/// [transpose]
+)
+
+HIDE(
+/// [transform]
+using fnsig = metal::list<void(), int(), char(), float()>;
+using fnptr = metal::list<void(*)(), int(*)(), char(*)(), float(*)()>;
+using fnref = metal::list<void(&)(), int(&)(), char(&)(), float(&)()>;
+
+IS_SAME(
+    metal::transform<metal::lambda<std::common_type_t>, fnsig, fnptr, fnref>,
+    metal::list<void(*)(), int(*)(), char(*)(), float(*)()>
+);
+/// [transform]
+)
+
+HIDE(
+/// [fold_left]
+using l = metal::list<short, int, long>;
+
+IS_SAME(
+    metal::fold_left<l, void, metal::lambda<metal::list>>,
+    metal::list<metal::list<metal::list<void, short>, int>, long>
+);
+/// [fold_left]
+)
diff --git a/example/src/map.cpp b/example/src/map.cpp
index ae41d97c..0184939d 100644
--- a/example/src/map.cpp
+++ b/example/src/map.cpp
@@ -57,7 +57,7 @@ using m = metal::map<
 
 IS_SAME(metal::is_map<m>, metal::true_);
 IS_SAME(metal::is_map<metal::list<>>, metal::true_);
-IS_SAME(metal::is_map<metal::list<int, int*>>, metal::false_);
+IS_SAME(metal::is_map<metal::pair<int, int*>>, metal::false_);
 /// [is_map]
 )
 
@@ -104,6 +104,26 @@ IS_SAME(metal::at_key<m, float>, metal::number<sizeof(float)>);
 /// [at_key]
 )
 
+HIDE(
+/// [insert_key]
+using m = metal::map<
+    metal::pair<int, metal::number<sizeof(int)>>,
+    metal::pair<char, metal::number<sizeof(char)>>,
+    metal::pair<float, metal::number<sizeof(float)>>
+>;
+
+IS_SAME(
+    metal::insert_key<m, void, metal::number<0>>,
+    metal::map<
+        metal::pair<int, metal::number<sizeof(int)>>,
+        metal::pair<char, metal::number<sizeof(char)>>,
+        metal::pair<float, metal::number<sizeof(float)>>,
+        metal::pair<void, metal::number<0>>
+    >
+);
+/// [insert_key]
+)
+
 HIDE(
 /// [erase_key]
 using m = metal::map<
diff --git a/include/metal/config/version.hpp b/include/metal/config/version.hpp
index 58726356..cdfad0b2 100644
--- a/include/metal/config/version.hpp
+++ b/include/metal/config/version.hpp
@@ -30,7 +30,7 @@
 ///
 /// ### See Also
 /// \see [Semantic Versioning](http://semver.org/)
-#define METAL_PATCH 2
+#define METAL_PATCH 3
 
 /// \ingroup config
 /// \hideinitializer
diff --git a/include/metal/detail/declptr.hpp b/include/metal/detail/declptr.hpp
index fe84ca6d..1b0a6c3b 100644
--- a/include/metal/detail/declptr.hpp
+++ b/include/metal/detail/declptr.hpp
@@ -7,11 +7,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename T>
         T* declptr();
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/detail/lookup.hpp b/include/metal/detail/lookup.hpp
index f614ddf5..6bba903b 100644
--- a/include/metal/detail/lookup.hpp
+++ b/include/metal/detail/lookup.hpp
@@ -20,6 +20,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename, typename>
@@ -104,6 +105,7 @@ namespace metal
         template<typename vals, typename keys, typename key>
         using lookup = typename _lookup<vals, keys, key>::type;
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/lambda/arg.hpp b/include/metal/lambda/arg.hpp
index 1c7c2b19..4b3d2ffa 100644
--- a/include/metal/lambda/arg.hpp
+++ b/include/metal/lambda/arg.hpp
@@ -16,6 +16,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<std::uintmax_t n>
@@ -31,6 +32,7 @@ namespace metal
         struct arg_impl<0U>
         {};
     }
+    /// \endcond
 
     /// \ingroup lambda
     ///
diff --git a/include/metal/lambda/bind.hpp b/include/metal/lambda/bind.hpp
index 763cf163..d36404be 100644
--- a/include/metal/lambda/bind.hpp
+++ b/include/metal/lambda/bind.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename lbd, typename... vals>
         struct _bind;
     }
+    /// \endcond
 
     /// \ingroup lambda
     ///
@@ -30,6 +32,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<template<typename...> class, template<typename...> class...>
@@ -81,6 +84,7 @@ namespace metal
             using type = lambda<impl>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/lambda/invoke.hpp b/include/metal/lambda/invoke.hpp
index fa05a8e1..6849ee0b 100644
--- a/include/metal/lambda/invoke.hpp
+++ b/include/metal/lambda/invoke.hpp
@@ -16,6 +16,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename lbd, typename seq, typename = true_>
@@ -24,6 +25,7 @@ namespace metal
         template<typename lbd, typename... args>
         struct _invoke;
     }
+    /// \endcond
 
     /// \ingroup lambda
     ///
@@ -51,6 +53,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename lbd, typename seq, typename>
@@ -80,6 +83,7 @@ namespace metal
             _invoke_impl<lbd, list<args...>>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/lambda/lambda.hpp b/include/metal/lambda/lambda.hpp
index ca82a32a..34e8024c 100644
--- a/include/metal/lambda/lambda.hpp
+++ b/include/metal/lambda/lambda.hpp
@@ -9,6 +9,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -17,11 +18,15 @@ namespace metal
         template<template<typename...> class expr>
         struct lambda {};
     }
+    /// \endcond
 
     /// \ingroup lambda
     ///
     /// ### Description
     /// ...
+    ///
+    /// ### See Also
+    /// \see lambda, is_value, is_number, is_pair, is_list, is_map
     template<typename val>
     using is_lambda = typename detail::_is_lambda<val>::type;
 
@@ -37,6 +42,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -49,6 +55,7 @@ namespace metal
             true_
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/lambda/partial.hpp b/include/metal/lambda/partial.hpp
index 1f0ecc77..927b1686 100644
--- a/include/metal/lambda/partial.hpp
+++ b/include/metal/lambda/partial.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename lbd, typename... vals>
         struct _partial;
     }
+    /// \endcond
 
     /// \ingroup lambda
     ///
@@ -28,6 +30,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename lbd, typename... vals>
@@ -49,6 +52,7 @@ namespace metal
             using type = lambda<expr>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/lambda/quote.hpp b/include/metal/lambda/quote.hpp
index 1fccdc8e..9d349618 100644
--- a/include/metal/lambda/quote.hpp
+++ b/include/metal/lambda/quote.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
         struct _quote;
     }
+    /// \endcond
 
     /// \ingroup lambda
     ///
@@ -27,6 +29,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -38,6 +41,7 @@ namespace metal
             using type = lambda<impl>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/all.hpp b/include/metal/list/all.hpp
index 7744bff6..3032e0ef 100644
--- a/include/metal/list/all.hpp
+++ b/include/metal/list/all.hpp
@@ -17,7 +17,33 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Checks whether a predicate holds for all elements of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::all<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \number
+    /// \semantics:
+    ///     If `metal::invoke<lbd, l[i]>{} != false` for all `l[i]` contained in
+    ///     `l`, then
+    ///     \code
+    ///         using result = metal::true_;
+    ///     \endcode
+    ///     otherwise
+    ///     \code
+    ///         using result = metal::false_;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp all
+    ///
+    /// ### See Also
+    /// \see list, any, none
     template<typename seq, typename lbd>
     using all =
         metal::apply<metal::lambda<metal::and_>, metal::transform<lbd, seq>>;
diff --git a/include/metal/list/any.hpp b/include/metal/list/any.hpp
index 5ebc63e4..66f347a9 100644
--- a/include/metal/list/any.hpp
+++ b/include/metal/list/any.hpp
@@ -17,7 +17,33 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Checks whether a predicate holds for at least some element of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::any<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \number
+    /// \semantics:
+    ///     If `metal::invoke<lbd, l[i]>{} != false` for at least some `l[i]`
+    ///     contained in `l`, then
+    ///     \code
+    ///         using result = metal::true_;
+    ///     \endcode
+    ///     otherwise
+    ///     \code
+    ///         using result = metal::false_;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp any
+    ///
+    /// ### See Also
+    /// \see list, all, none
     template<typename seq, typename lbd>
     using any =
         metal::apply<metal::lambda<metal::or_>, metal::transform<lbd, seq>>;
diff --git a/include/metal/list/append.hpp b/include/metal/list/append.hpp
index eb60b360..c2895399 100644
--- a/include/metal/list/append.hpp
+++ b/include/metal/list/append.hpp
@@ -15,7 +15,28 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Inserts \values at the end of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \values `val_0, ..., val_n-1`
+    /// \code
+    ///     using result = metal::append<l, val_0, ..., val_n-1>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[m-1]`, then
+    ///     \code
+    ///         using result = metal::list<
+    ///             l[0], ..., l[m-1], val_0, ..., val_n-1
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp append
+    ///
+    /// ### See Also
+    /// \see list, insert, prepend
     template<typename seq, typename head, typename... tail>
     using append = metal::join<seq, metal::list<head, tail...>>;
 }
diff --git a/include/metal/list/at.hpp b/include/metal/list/at.hpp
index 68ccfaf7..d4642a91 100644
--- a/include/metal/list/at.hpp
+++ b/include/metal/list/at.hpp
@@ -16,7 +16,28 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Retrieves an element of a \list at an arbitrary position.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \number `num`
+    /// \code
+    ///     using result = metal::at<l, num>;
+    /// \endcode
+    ///
+    /// \pre: `metal::number<0>{} &le; num{} < metal::size<l>{}`
+    /// \returns: \value
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[i], ..., l[m-1]` and
+    ///     `num{} == i`, then
+    ///     \code
+    ///         using result = l[i];
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp at
+    ///
+    /// ### See Also
+    /// \see list, front, back
     template<typename seq, typename num>
     using at = detail::lookup<seq, indices<seq>, num>;
 }
diff --git a/include/metal/list/back.hpp b/include/metal/list/back.hpp
index 68b08e6f..6b07077f 100644
--- a/include/metal/list/back.hpp
+++ b/include/metal/list/back.hpp
@@ -16,7 +16,26 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Retrieves the last element of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l`
+    /// \code
+    ///     using result = metal::back<l>;
+    /// \endcode
+    ///
+    /// \returns: \value
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[m-1]`, then
+    ///     \code
+    ///         using result = l[m-1];
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp back
+    ///
+    /// ### See Also
+    /// \see list, at, front
     template<typename seq>
     using back = metal::at<seq, metal::dec<metal::size<seq>>>;
 }
diff --git a/include/metal/list/contains.hpp b/include/metal/list/contains.hpp
index c6c84cf7..66665b54 100644
--- a/include/metal/list/contains.hpp
+++ b/include/metal/list/contains.hpp
@@ -18,7 +18,30 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Checks whether a \value is contained in a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \value `val`
+    /// \code
+    ///     using result = metal::contains<l, val>;
+    /// \endcode
+    ///
+    /// \returns: \number
+    /// \semantics:
+    ///     If `val` is contained in `l`, then
+    ///     \code
+    ///         using result = metal::true_;
+    ///     \endcode
+    ///     otherwise
+    ///     \code
+    ///         using result = metal::false_;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp contains
+    ///
+    /// ### See Also
+    /// \see list, count, find
     template<typename seq, typename val>
     using contains =
         metal::any<seq, metal::partial<metal::lambda<metal::same>, val>>;
diff --git a/include/metal/list/copy.hpp b/include/metal/list/copy.hpp
index 88e73675..202f18a6 100644
--- a/include/metal/list/copy.hpp
+++ b/include/metal/list/copy.hpp
@@ -17,7 +17,29 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Removes all elements from a \list except for those that are the same as
+    /// some \value.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \value `val`
+    /// \code
+    ///     using result = metal::copy<l, val>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<...>;
+    ///     \endcode
+    ///     where `result` contains all and only the occurrences of `val` in
+    ///     `l`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp copy
+    ///
+    /// ### See Also
+    /// \see list, copy_if, remove, replace
     template<typename seq, typename val>
     using copy =
         metal::copy_if<seq, metal::partial<metal::lambda<metal::same>, val>>;
diff --git a/include/metal/list/copy_if.hpp b/include/metal/list/copy_if.hpp
index e8c319c8..5daa5b6b 100644
--- a/include/metal/list/copy_if.hpp
+++ b/include/metal/list/copy_if.hpp
@@ -11,16 +11,42 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq, typename nums>
         struct _copy_if_impl;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Removes all elements from a \list except for those that satisfy a
+    /// predicate.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::copy_if<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<...>;
+    ///     \endcode
+    ///     where `result` contains all and only the elements `l[i]` in `l` for
+    ///     which `metal::invoke<lbd, l[i]>{} != false`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp copy_if
+    ///
+    /// ### See Also
+    /// \see list, copy, remove_if, replace_if
     template<typename seq, typename lbd>
     using copy_if =
         typename detail::_copy_if_impl<seq, transform<lbd, seq>>::type;
@@ -33,6 +59,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq, typename nums>
@@ -50,6 +77,7 @@ namespace metal
             _join<if_<number<vs>, list<vals>, list<>>...>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/count.hpp b/include/metal/list/count.hpp
index 6eef5db1..b4ee4b5c 100644
--- a/include/metal/list/count.hpp
+++ b/include/metal/list/count.hpp
@@ -17,7 +17,27 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Counts the occurrences of a \value in a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \value `val`
+    /// \code
+    ///     using result = metal::count<l, val>;
+    /// \endcode
+    ///
+    /// \returns: \number
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::number<n>;
+    ///     \endcode
+    ///     where `n` is the number of occurrences of `val` in `l`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp count
+    ///
+    /// ### See Also
+    /// \see list, count_if, contains, find
     template<typename seq, typename val>
     using count =
         metal::count_if<seq, metal::partial<metal::lambda<metal::same>, val>>;
diff --git a/include/metal/list/count_if.hpp b/include/metal/list/count_if.hpp
index 933201de..78539ccf 100644
--- a/include/metal/list/count_if.hpp
+++ b/include/metal/list/count_if.hpp
@@ -19,7 +19,30 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Counts the elements in a \list that satisfy a predicate.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::count_if<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \number
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::number<n>;
+    ///     \endcode
+    ///     where `n` is the number of occurrences of some `l[i]` in `l`, such
+    ///     that `metal::invoke<lbd, l[i]>{} != false`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp count_if
+    ///
+    /// ### See Also
+    /// \see list, count, all, any, none, find_if
     template<typename seq, typename lbd>
     using count_if = metal::apply<
         metal::partial<metal::lambda<metal::add>, metal::number<0>>,
diff --git a/include/metal/list/drop.hpp b/include/metal/list/drop.hpp
index fdbe111c..94d5c251 100644
--- a/include/metal/list/drop.hpp
+++ b/include/metal/list/drop.hpp
@@ -15,7 +15,29 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Removes all elements from the beginning up to an arbitrary index of a
+    /// \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \number `num`
+    /// \code
+    ///     using result = metal::drop<l, num>;
+    /// \endcode
+    ///
+    /// \pre: `metal::number<0>{} &le; num{} &le; metal::size<l>{}`
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[i], ..., l[m-1]` and
+    ///     `num{} == i`, then
+    ///     \code
+    ///         using result = metal::list<l[i], ..., l[m-1]>;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp drop
+    ///
+    /// ### See Also
+    /// \see list, range, erase, take
     template<typename seq, typename n>
     using drop = metal::range<seq, n, metal::size<seq>>;
 }
diff --git a/include/metal/list/empty.hpp b/include/metal/list/empty.hpp
index b1257545..1a26c4c3 100644
--- a/include/metal/list/empty.hpp
+++ b/include/metal/list/empty.hpp
@@ -15,7 +15,30 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Checks whether a \list has no elements.
+    ///
+    /// ### Usage
+    /// For any \list `l`
+    /// \code
+    ///     using result = metal::empty<l>;
+    /// \endcode
+    ///
+    /// \returns: \number
+    /// \semantics:
+    ///     If `l` contains at least one element, then
+    ///     \code
+    ///         using result = metal::false_;
+    ///     \endcode
+    ///     otherwise
+    ///     \code
+    ///         using result = metal::true_;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp empty
+    ///
+    /// ### See Also
+    /// \see list, size
     template<typename seq>
     using empty = metal::not_<metal::size<seq>>;
 }
diff --git a/include/metal/list/erase.hpp b/include/metal/list/erase.hpp
index 5d3495d9..8b9b0b28 100644
--- a/include/metal/list/erase.hpp
+++ b/include/metal/list/erase.hpp
@@ -19,7 +19,32 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Removes all elements between two arbitrary indices of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \numbers `beg` and `end`
+    /// \code
+    ///     using result = metal::erase<l, beg, end>;
+    /// \endcode
+    ///
+    /// \pre: `metal::number<0>{} &le; beg{} &le; metal::size<l>{}` and
+    /// `metal::number<0>{} &le; end{} &le; metal::size<l>{}`
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[i], ..., l[j], ..., l[m-1]`
+    ///     and either `beg{} == i` and `end{} == j` or
+    ///     `beg{} == j` and `end{} == i`, then
+    ///     \code
+    ///         using result = metal::list<
+    ///             l[0], ..., l[i-1], l[j], ..., l[m-1]
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp erase
+    ///
+    /// ### See Also
+    /// \see list, range, take, drop
     template<typename seq, typename beg, typename end = inc<beg>>
     using erase = metal::join<
         metal::take<seq, metal::min<beg, end>>,
diff --git a/include/metal/list/find.hpp b/include/metal/list/find.hpp
index 5308046e..f8440d88 100644
--- a/include/metal/list/find.hpp
+++ b/include/metal/list/find.hpp
@@ -17,7 +17,31 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Returns the index of the first occurrence of a \value in a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \value `val`
+    /// \code
+    ///     using result = metal::find<l, val>;
+    /// \endcode
+    ///
+    /// \returns: \number
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::number<i>;
+    ///     \endcode
+    ///     where `i` is index of the first occurrence of `val` in `l`,
+    ///     otherwise
+    ///     \code
+    ///         using result = metal::size<l>;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp find
+    ///
+    /// ### See Also
+    /// \see list, find_if, count, contains
     template<typename seq, typename val>
     using find =
         metal::find_if<seq, metal::partial<metal::lambda<metal::same>, val>>;
diff --git a/include/metal/list/find_if.hpp b/include/metal/list/find_if.hpp
index 585b2a90..8a775966 100644
--- a/include/metal/list/find_if.hpp
+++ b/include/metal/list/find_if.hpp
@@ -11,16 +11,45 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq>
         struct _find_if_impl;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Returns the index of the first element of a \list that satisfy a
+    /// predicate.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::find_if<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \number
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::number<i>;
+    ///     \endcode
+    ///     where `i` is such that `l[i]` is the first element in `l` for which
+    ///     `metal::invoke<lbd, l[i]>{} != false`, otherwise
+    ///     \code
+    ///         using result = metal::size<l>;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp find_if
+    ///
+    /// ### See Also
+    /// \see list, find, all, any, none, count_if
     template<typename seq, typename lbd>
     using find_if = typename detail::_find_if_impl<transform<lbd, seq>>::type;
 }
@@ -37,6 +66,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq>
@@ -82,6 +112,7 @@ namespace metal
         {};
 #endif
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/flatten.hpp b/include/metal/list/flatten.hpp
index e751f64d..d0ef384e 100644
--- a/include/metal/list/flatten.hpp
+++ b/include/metal/list/flatten.hpp
@@ -9,16 +9,40 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq>
         struct _flatten;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Flattens a \list by recursively replacing its sub-\lists by their
+    /// contents.
+    ///
+    /// ### Usage
+    /// For any \list `l`
+    /// \code
+    ///     using result = metal::flatten<l>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<...>;
+    ///     \endcode
+    ///     where `result` is *flat* (i.e. contains no sub-\lists) and contains
+    ///     all the elements in `l` and in all its sub-\lists.
+    ///
+    /// ### Example
+    /// \snippet list.cpp flatten
+    ///
+    /// ### See Also
+    /// \see list, join
     template<typename seq>
     using flatten = typename detail::_flatten<seq>::type;
 }
@@ -28,6 +52,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq>
@@ -56,6 +81,7 @@ namespace metal
             using type = list<>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/fold_left.hpp b/include/metal/list/fold_left.hpp
index 8cf0c7f1..f9f13aed 100644
--- a/include/metal/list/fold_left.hpp
+++ b/include/metal/list/fold_left.hpp
@@ -9,16 +9,42 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq, typename state, typename lbd>
         struct _fold_left;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Computes the recursive invocation of a binary \lambda to the result of
+    /// the previous invocation (starting with some arbitrary \value) and each
+    /// element of a \list traversed from the beginning to the end.
+    ///
+    /// ### Usage
+    /// For any \list `l`, \value `val` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::fold_left<l, val, lbd>;
+    /// \endcode
+    ///
+    /// \returns: \value
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[m-1]`, then
+    ///     \code
+    ///         using result =
+    ///             lbd(... lbd(lbd(lbd(val, l[0]), l[1]), l[2]), ..., l[m-1])
+    ///     \endcode
+    ///     where the notation `lbd(x, y)` stands for
+    ///     `metal::invoke<lbd, x, y>`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp fold_left
+    ///
+    /// ### See Also
+    /// \see list, fold_right
     template<typename seq, typename state, typename lbd>
     using fold_left = typename detail::_fold_left<seq, state, lbd>::type;
 }
@@ -30,6 +56,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename cons, typename state, typename lbd, typename = true_>
@@ -269,6 +296,7 @@ namespace metal
             _fold_left_impl<cons<vals...>, state, lbd>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/fold_right.hpp b/include/metal/list/fold_right.hpp
index fa32a053..df474762 100644
--- a/include/metal/list/fold_right.hpp
+++ b/include/metal/list/fold_right.hpp
@@ -15,7 +15,7 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// TODO
     template<typename seq, typename state, typename lbd>
     using fold_right = metal::fold_left<metal::reverse<seq>, state, lbd>;
 }
diff --git a/include/metal/list/front.hpp b/include/metal/list/front.hpp
index 4b6d91b7..cdde31a2 100644
--- a/include/metal/list/front.hpp
+++ b/include/metal/list/front.hpp
@@ -15,7 +15,26 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Retrieves the first element of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l`
+    /// \code
+    ///     using result = metal::front<l>;
+    /// \endcode
+    ///
+    /// \returns: \value
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[m-1]`, then
+    ///     \code
+    ///         using result = l[0];
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp front
+    ///
+    /// ### See Also
+    /// \see list, at, back
     template<typename seq>
     using front = metal::at<seq, metal::number<0>>;
 }
diff --git a/include/metal/list/indices.hpp b/include/metal/list/indices.hpp
index a95bdaa2..032e326a 100644
--- a/include/metal/list/indices.hpp
+++ b/include/metal/list/indices.hpp
@@ -16,7 +16,28 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Replaces each element of a \list by its corresponding index.
+    ///
+    /// ### Usage
+    /// For any \list `l`
+    /// \code
+    ///     using result = metal::indices<l>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[m-1]`, then
+    ///     \code
+    ///         using result = metal::list<
+    ///             metal::number<0>, metal::number<>..., metal::number<m-1>
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp indices
+    ///
+    /// ### See Also
+    /// \see list, enumerate
     template<typename seq>
     using indices = metal::enumerate<metal::number<0>, metal::size<seq>>;
 }
diff --git a/include/metal/list/insert.hpp b/include/metal/list/insert.hpp
index 957f3542..df016a64 100644
--- a/include/metal/list/insert.hpp
+++ b/include/metal/list/insert.hpp
@@ -15,9 +15,30 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
-    template<typename seq, typename n, typename val>
-    using insert = metal::splice<seq, n, metal::list<val>>;
+    /// Inserts a \value in a \list at an arbitrary position.
+    ///
+    /// ### Usage
+    /// For any \list `l`, \number `num` and \value `val`
+    /// \code
+    ///     using result = metal::insert<l, num, val>;
+    /// \endcode
+    ///
+    /// \pre: `metal::number<0>{} &le; num{} &le; metal::size<l>{}`
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[i], ..., l[m-1]` and
+    ///     `num{} == i`, then
+    ///     \code
+    ///         using result = metal::list<l[0], ..., val, l[i], ..., l[m-1]>;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp insert
+    ///
+    /// ### See Also
+    /// \see list, prepend, append, splice
+    template<typename seq, typename num, typename val>
+    using insert = metal::splice<seq, num, metal::list<val>>;
 }
 
 #endif
diff --git a/include/metal/list/join.hpp b/include/metal/list/join.hpp
index b7246104..551e7290 100644
--- a/include/metal/list/join.hpp
+++ b/include/metal/list/join.hpp
@@ -9,16 +9,39 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename... seqs>
         struct _join;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Concatenates \lists.
+    ///
+    /// ### Usage
+    /// For any \lists `l_0, ..., l_n-1`
+    /// \code
+    ///     using result = metal::join<l_0, ..., l_n-1>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<l_0[:], ...[:], l_n-1[:]>;
+    ///     \endcode
+    ///     where the notation `l[:]` stands for the expansion of all elements
+    ///     contained in `l`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp join
+    ///
+    /// ### See Also
+    /// \see list, flatten
     template<typename head, typename... tail>
     using join = typename detail::_join<head, tail...>::type;
 }
@@ -31,6 +54,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<
@@ -191,6 +215,7 @@ namespace metal
             _if_<is_list<seq>, seq>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/list.hpp b/include/metal/list/list.hpp
index a24bdbad..0ab93dbc 100644
--- a/include/metal/list/list.hpp
+++ b/include/metal/list/list.hpp
@@ -9,6 +9,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -17,18 +18,53 @@ namespace metal
         template<typename... vals>
         struct list {};
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Checks whether some \value is a \list.
+    ///
+    /// ### Usage
+    /// For any \value `val`
+    /// \code
+    ///     using result = metal::is_list<val>;
+    /// \endcode
+    ///
+    /// \returns: \number
+    /// \semantics:
+    ///     If `val` is a \list, then
+    ///     \code
+    ///         using result = metal::true_;
+    ///     \endcode
+    ///     otherwise
+    ///     \code
+    ///         using result = metal::false_;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp is_list
+    ///
+    /// ### See Also
+    /// \see list, is_value, is_number, is_lambda, is_pair, is_map
     template<typename val>
     using is_list = typename detail::_is_list<val>::type;
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Constructs a \list out of a sequence of \values.
+    ///
+    /// ### Usage
+    /// For any \values `val_0, ..., val_n-1`
+    /// \code
+    ///     using result = metal::pair<val_0, ..., val_n-1>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    ///
+    /// ### See Also
+    /// \see is_list
     template<typename... vals>
     using list = detail::list<vals...>;
 }
@@ -37,6 +73,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -49,6 +86,7 @@ namespace metal
             true_
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/none.hpp b/include/metal/list/none.hpp
index 6572d94e..ecd8a50b 100644
--- a/include/metal/list/none.hpp
+++ b/include/metal/list/none.hpp
@@ -15,7 +15,33 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Checks whether a predicate does not hold for any element of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::none<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \number
+    /// \semantics:
+    ///     If `metal::invoke<lbd, l[i]>{} == false` for all `l[i]` contained in
+    ///     `l`, then
+    ///     \code
+    ///         using result = metal::true_;
+    ///     \endcode
+    ///     otherwise
+    ///     \code
+    ///         using result = metal::false_;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp none
+    ///
+    /// ### See Also
+    /// \see list, all, any
     template<typename seq, typename lbd>
     using none = metal::not_<metal::any<seq, lbd>>;
 }
diff --git a/include/metal/list/partition.hpp b/include/metal/list/partition.hpp
index 59a47edf..77db90a8 100644
--- a/include/metal/list/partition.hpp
+++ b/include/metal/list/partition.hpp
@@ -19,7 +19,31 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Splits a \list in two according to a predicate.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::partition<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \pair
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::pair<l_1, l_2>;
+    ///     \endcode
+    ///     where `l_1` contains all and only the elements `l[i]` in `l` for
+    ///     which `metal::invoke<lbd, l[i]>{} != false` and `l_2` contains the
+    ///     remaining elements.
+    ///
+    /// ### Example
+    /// \snippet list.cpp partition
+    ///
+    /// ### See Also
+    /// \see list, copy_if, remove_if
     template<typename seq, typename lbd>
     using partition =
         metal::pair<metal::copy_if<seq, lbd>, metal::remove_if<seq, lbd>>;
diff --git a/include/metal/list/prepend.hpp b/include/metal/list/prepend.hpp
index a9a3bb33..6d757cbc 100644
--- a/include/metal/list/prepend.hpp
+++ b/include/metal/list/prepend.hpp
@@ -15,7 +15,28 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Inserts \values at the beginning of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \values `val_0, ..., val_n-1`
+    /// \code
+    ///     using result = metal::prepend<l, val_0, ..., val_n-1>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[m-1]`, then
+    ///     \code
+    ///         using result = metal::list<
+    ///             val_0, ..., val_n-1, l[0], ..., l[m-1]
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp prepend
+    ///
+    /// ### See Also
+    /// \see list, insert, append
     template<typename seq, typename head, typename... tail>
     using prepend = metal::join<metal::list<head, tail...>, seq>;
 }
diff --git a/include/metal/list/range.hpp b/include/metal/list/range.hpp
index 6a401629..caa71524 100644
--- a/include/metal/list/range.hpp
+++ b/include/metal/list/range.hpp
@@ -16,6 +16,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq, typename beg, typename end>
@@ -24,11 +25,38 @@ namespace metal
         template<typename seq, typename beg, typename end>
         using range = typename detail::_range<seq, beg, end>::type;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Returns a contiguous subsequence of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \numbers `beg` and `end`
+    /// \code
+    ///     using result = metal::range<l, beg, end>;
+    /// \endcode
+    ///
+    /// \pre: `metal::number<0>{} &le; beg{} &le; metal::size<l>{}` and
+    /// `metal::number<0>{} &le; end{} &le; metal::size<l>{}`
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[i], ..., l[j], ..., l[m-1]`,
+    ///     `beg{} == i` and `end{} == j`, then
+    ///     \code
+    ///         using result = metal::list<l[i], ..., l[j-1]>;
+    ///     \endcode
+    ///     otherwise, if `beg{} == j` and `end{} == i`, then
+    ///     \code
+    ///         using result = metal::list<l[j-1], ..., l[i]>;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp range
+    ///
+    /// ### See Also
+    /// \see list, erase, take, drop
     template<typename seq, typename beg, typename end>
     using range = detail::range<
         seq,
@@ -50,6 +78,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename> using void_ = void;
@@ -114,6 +143,7 @@ namespace metal
             using type = list<>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/remove.hpp b/include/metal/list/remove.hpp
index d13f9d1e..679a9bae 100644
--- a/include/metal/list/remove.hpp
+++ b/include/metal/list/remove.hpp
@@ -17,7 +17,28 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Removes all elements from a \list that are the same as some \value.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \value `val`
+    /// \code
+    ///     using result = metal::remove<l, val>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<...>;
+    ///     \endcode
+    ///     where `result` contains all and only the elements in `l` which are
+    ///     distinct from `val`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp remove
+    ///
+    /// ### See Also
+    /// \see list, remove_if, copy, replace
     template<typename seq, typename val>
     using remove =
         metal::remove_if<seq, metal::partial<metal::lambda<metal::same>, val>>;
diff --git a/include/metal/list/remove_if.hpp b/include/metal/list/remove_if.hpp
index 9c9878b4..f7b8657e 100644
--- a/include/metal/list/remove_if.hpp
+++ b/include/metal/list/remove_if.hpp
@@ -17,7 +17,30 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Removes all elements from a \list that satisfy a predicate.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::remove_if<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<...>;
+    ///     \endcode
+    ///     where `result` contains all and only the elements `l[i]` in `l` for
+    ///     which `metal::invoke<lbd, l[i]>{} == false`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp remove_if
+    ///
+    /// ### See Also
+    /// \see list, remove, copy_if, replace_if
     template<typename seq, typename lbd>
     using remove_if =
         metal::copy_if<seq, metal::bind<metal::lambda<metal::not_>, lbd>>;
diff --git a/include/metal/list/replace.hpp b/include/metal/list/replace.hpp
index b24f0829..e407df4d 100644
--- a/include/metal/list/replace.hpp
+++ b/include/metal/list/replace.hpp
@@ -17,7 +17,28 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Replaces every occurrence of a \value in a \list by another \value.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \values `val_1` and `val_2`
+    /// \code
+    ///     using result = metal::replace<l, val_1, val_2>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<...>;
+    ///     \endcode
+    ///     where `result` contains all and only the elements in `l`, except
+    ///     that every occurrence of `val_1` has been replaced by `val_2`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp replace
+    ///
+    /// ### See Also
+    /// \see list, replace_if, copy, remove
     template<typename seq, typename from, typename to>
     using replace = metal::replace_if<
         seq, metal::partial<metal::lambda<metal::same>, from>, to
diff --git a/include/metal/list/replace_if.hpp b/include/metal/list/replace_if.hpp
index f3d4ff8d..1bb94885 100644
--- a/include/metal/list/replace_if.hpp
+++ b/include/metal/list/replace_if.hpp
@@ -11,16 +11,43 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename, typename, typename>
         struct _replace_if_impl;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Replaces every element in a \list that satisfies a predicate by some
+    /// \value.
+    ///
+    /// ### Usage
+    /// For any \list `l`, \lambda `lbd` and \value `val`
+    /// \code
+    ///     using result = metal::replace_if<l, lbd, val>;
+    /// \endcode
+    ///
+    /// \pre: For any element `l[i]` contained in `l`,
+    /// `metal::invoke<lbd, l[i]>` returns a \number
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<...>;
+    ///     \endcode
+    ///     where `result` contains all and only the elements in `l`, except
+    ///     that every element `l[i]` for which
+    ///     `metal::invoke<lbd, l[i]>{} != false` has been replaced by `val`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp replace_if
+    ///
+    /// ### See Also
+    /// \see list, replace, copy_if, remove_if
     template<typename seq, typename lbd, typename val>
     using replace_if =
         typename detail::_replace_if_impl<seq, transform<lbd, seq>, val>::type;
@@ -32,6 +59,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename, typename, typename>
@@ -50,6 +78,7 @@ namespace metal
             using type = list<if_<number<vs>, val, vals>...>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/reverse.hpp b/include/metal/list/reverse.hpp
index 744213f4..5610552f 100644
--- a/include/metal/list/reverse.hpp
+++ b/include/metal/list/reverse.hpp
@@ -9,16 +9,37 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq>
         struct _reverse;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Reverses the order of the elements of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l`
+    /// \code
+    ///     using result = metal::reverse<l>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[m-1]`, then
+    ///     \code
+    ///         using result = metal::list<l[m-1], ..., l[0]>;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp reverse
+    ///
+    /// ### See Also
+    /// \see list, rotate, sort
     template<typename seq>
     using reverse = typename detail::_reverse<seq>::type;
 }
@@ -29,6 +50,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<int_ n>
@@ -126,6 +148,7 @@ namespace metal
                 typename _reverse_impl<sizeof...(vals)>::template type<vals...>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/rotate.hpp b/include/metal/list/rotate.hpp
index 3553ca10..8f8a92e8 100644
--- a/include/metal/list/rotate.hpp
+++ b/include/metal/list/rotate.hpp
@@ -11,16 +11,40 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq, typename num, typename = size<seq>>
         struct _rotate;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Rotates the elements of a \list around a pivot.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \number `num`
+    /// \code
+    ///     using result = metal::rotate<l, num>;
+    /// \endcode
+    ///
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[i-1], l[i], ..., l[m-1]` and
+    ///     `num{} % m == i`, then
+    ///     \code
+    ///         using result = metal::list<
+    ///             l[i], ..., l[m-1], l[0], ..., l[i-1]
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp rotate
+    ///
+    /// ### See Also
+    /// \see list, reverse, sort
     template<typename seq, typename num>
     using rotate = typename detail::_rotate<seq, num>::type;
 }
@@ -30,6 +54,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<int_ n>
@@ -134,6 +159,7 @@ namespace metal
             using type = list<>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/size.hpp b/include/metal/list/size.hpp
index 56cbf867..a6b1d749 100644
--- a/include/metal/list/size.hpp
+++ b/include/metal/list/size.hpp
@@ -9,16 +9,37 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq>
         struct _size;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Returns the number of elements in a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l`
+    /// \code
+    ///     using result = metal::size<l>;
+    /// \endcode
+    ///
+    /// \returns: \number
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[m-1]`, then
+    ///     \code
+    ///         using result = metal::number<m>;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp size
+    ///
+    /// ### See Also
+    /// \see list, empty
     template<typename seq>
     using size = typename detail::_size<seq>::type;
 }
@@ -28,6 +49,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq>
@@ -39,6 +61,7 @@ namespace metal
             number<sizeof...(vals)>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/slice.hpp b/include/metal/list/slice.hpp
index 2f75f5e0..4d8d0a33 100644
--- a/include/metal/list/slice.hpp
+++ b/include/metal/list/slice.hpp
@@ -21,7 +21,7 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// TODO
     template<
         typename seq,
         typename start, typename size, typename stride = number<1>
diff --git a/include/metal/list/sort.hpp b/include/metal/list/sort.hpp
index d121825c..815002c2 100644
--- a/include/metal/list/sort.hpp
+++ b/include/metal/list/sort.hpp
@@ -9,16 +9,46 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename seq, typename lbd>
         struct _sort;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Sorts the elements of a \list according to an ordering relation.
+    ///
+    /// \tip{The sorting is [stable] if the ordering relation is [strict].}
+    /// [stable]: https://en.wikipedia.org/wiki/Sorting_algorithm#Stability
+    /// [strict]: https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings
+    ///
+    /// ### Usage
+    /// For any \list `l` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::sort<l, lbd>;
+    /// \endcode
+    ///
+    /// \pre: For any two \values `val_i` and `val_j` contained in `l`
+    /// `metal::invoke<lbd, val_i, val_j>` returns a \number
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<val_0, ..., val_m-1>;
+    ///     \endcode
+    ///     where `val_0, ..., val_m-1` is a permutation of the elements in `l`
+    ///     such that `metal::invoke<lbd, val_i, val_i+1>{} != false` for all
+    ///     `i` in `[0, m-2]`.
+    ///
+    /// ### Example
+    /// \snippet list.cpp sort
+    ///
+    /// ### See Also
+    /// \see list, reverse, rotate
     template<typename seq, typename lbd>
     using sort = typename detail::_sort<seq, lbd>::type;
 }
@@ -35,6 +65,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename, typename, typename, typename, typename = true_>
@@ -113,6 +144,7 @@ namespace metal
             _if_<is_lambda<lbd>, list<>>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/splice.hpp b/include/metal/list/splice.hpp
index 3c4e6a9a..94a00c1d 100644
--- a/include/metal/list/splice.hpp
+++ b/include/metal/list/splice.hpp
@@ -16,9 +16,33 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
-    template<typename seq, typename n, typename other>
-    using splice = metal::join<metal::take<seq, n>, other, metal::drop<seq, n>>;
+    /// Splices one \list into another at an arbitrary position.
+    ///
+    /// ### Usage
+    /// For any \lists `l_1` and `l_2` and \number `num`
+    /// \code
+    ///     using result = metal::splice<l_1, num, l_2>;
+    /// \endcode
+    ///
+    /// \pre: `metal::number<0>{} &le; num{} &le; metal::size<l_1>{}`
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l_1` contains elements `l_1[0], ..., l_1[i], ..., l_1[m-1]`,
+    ///     `l_2` contains elements `l_2[0], ..., l_2[n-1]` and `num{} == i`, then
+    ///     \code
+    ///         using result = metal::list<
+    ///             l_1[0], ..., l_2[0], ..., l_2[n-1], l_1[i], ..., l_1[m-1]
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp splice
+    ///
+    /// ### See Also
+    /// \see list, insert
+    template<typename seq, typename num, typename other>
+    using splice =
+        metal::join<metal::take<seq, num>, other, metal::drop<seq, num>>;
 }
 
 #endif
diff --git a/include/metal/list/take.hpp b/include/metal/list/take.hpp
index 547e5374..7d65310c 100644
--- a/include/metal/list/take.hpp
+++ b/include/metal/list/take.hpp
@@ -15,7 +15,28 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Removes all elements from the end down to an arbitrary index of a \list.
+    ///
+    /// ### Usage
+    /// For any \list `l` and \number `num`
+    /// \code
+    ///     using result = metal::take<l, num>;
+    /// \endcode
+    ///
+    /// \pre: `metal::number<0>{} &le; num{} &le; metal::size<l>{}`
+    /// \returns: \list
+    /// \semantics:
+    ///     If `l` contains elements `l[0], ..., l[i], ..., l[m-1]` and
+    ///     `num{} == i`, then
+    ///     \code
+    ///         using result = metal::list<l[0], ..., l[i-1]>;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp take
+    ///
+    /// ### See Also
+    /// \see list, range, erase, drop
     template<typename seq, typename n>
     using take = metal::range<seq, metal::number<0>, n>;
 }
diff --git a/include/metal/list/transform.hpp b/include/metal/list/transform.hpp
index 674b8e21..78c5bbe6 100644
--- a/include/metal/list/transform.hpp
+++ b/include/metal/list/transform.hpp
@@ -14,6 +14,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename lbd, typename head, typename... tail>
@@ -22,11 +23,37 @@ namespace metal
         template<typename lbd, typename head, typename... tail>
         using transform = typename _transform<lbd, head, tail...>::type;
     }
+    /// \endcond
 
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Transforms one or more \lists into a new \list through an arbitrary
+    /// n-ary \lambda.
+    ///
+    /// ### Usage
+    /// For any \lists `l_0, ..., l_n-1` and \lambda `lbd`
+    /// \code
+    ///     using result = metal::transform<lbd, l_0, ..., l_n-1>;
+    /// \endcode
+    ///
+    /// \pre: `metal::size<l_0>{} == metal::size<>{}... == metal::size<l_n-1>{}`
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<
+    ///             metal::invoke<lbd, l_0[0], ...[0], l_n-1[0]>,
+    ///             ...,
+    ///             metal::invoke<lbd, l_0[m-1], ...[m-1], l_n-1[m-1]>,
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp transform
+    ///
+    /// ### See Also
+    /// \see list, transpose
     template<typename lbd, typename head, typename... tail>
     using transform = typename if_<
         same<size<head>, size<tail>...>,
@@ -46,6 +73,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename, typename, typename = true_>
@@ -101,6 +129,7 @@ namespace metal
             using type = list<>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/list/transpose.hpp b/include/metal/list/transpose.hpp
index 0b63e0ad..69ffeef7 100644
--- a/include/metal/list/transpose.hpp
+++ b/include/metal/list/transpose.hpp
@@ -18,7 +18,32 @@ namespace metal
     /// \ingroup list
     ///
     /// ### Description
-    /// ...
+    /// Transposes a \list of \lists.
+    ///
+    /// ### Usage
+    /// For any \list `l`
+    /// \code
+    ///     using result = metal::transpose<l>;
+    /// \endcode
+    ///
+    /// \pre: If `l` contains elements `l[0], ..., l[m-1]`,
+    /// `metal::size<l[0]>{} == metal::size<>{}... == metal::size<l[n-1]>{}`
+    /// \returns: \list
+    /// \semantics:
+    ///     Equivalent to
+    ///     \code
+    ///         using result = metal::list<
+    ///             metal::list<l[0][0], ...[0], l[m-1][0]>,
+    ///             ...,
+    ///             metal::list<l[0][n-1], ...[n-1], l[m-1][n-1]>
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet list.cpp transpose
+    ///
+    /// ### See Also
+    /// \see list, transform
     template<typename seq>
     using transpose = metal::apply<
         metal::partial<
diff --git a/include/metal/map.hpp b/include/metal/map.hpp
index 6f7453b6..8024ccf0 100644
--- a/include/metal/map.hpp
+++ b/include/metal/map.hpp
@@ -10,6 +10,7 @@
 #include <metal/map/at_key.hpp>
 #include <metal/map/erase_key.hpp>
 #include <metal/map/has_key.hpp>
+#include <metal/map/insert_key.hpp>
 #include <metal/map/keys.hpp>
 #include <metal/map/map.hpp>
 #include <metal/map/order.hpp>
diff --git a/include/metal/map/at_key.hpp b/include/metal/map/at_key.hpp
index de7d9777..8fceee6c 100644
--- a/include/metal/map/at_key.hpp
+++ b/include/metal/map/at_key.hpp
@@ -37,7 +37,7 @@ namespace metal
     /// \snippet map.cpp at_key
     ///
     /// ### See Also
-    /// \see map, has_key, erase_key
+    /// \see map, has_key, insert_key, erase_key
     template<typename seq, typename key>
     using at_key = detail::lookup<values<seq>, keys<seq>, key>;
 }
diff --git a/include/metal/map/erase_key.hpp b/include/metal/map/erase_key.hpp
index 0170bf78..9c4629d9 100644
--- a/include/metal/map/erase_key.hpp
+++ b/include/metal/map/erase_key.hpp
@@ -37,7 +37,7 @@ namespace metal
     /// \snippet map.cpp erase_key
     ///
     /// ### See Also
-    /// \see map, has_key, at_key
+    /// \see map, has_key, at_key, insert_key
     template<typename seq, typename key>
     using erase_key = metal::erase<seq, metal::order<seq, key>>;
 }
diff --git a/include/metal/map/has_key.hpp b/include/metal/map/has_key.hpp
index 02d60d59..b39c15e8 100644
--- a/include/metal/map/has_key.hpp
+++ b/include/metal/map/has_key.hpp
@@ -38,7 +38,7 @@ namespace metal
     /// \snippet map.cpp has_key
     ///
     /// ### See Also
-    /// \see map, at_key, erase_key
+    /// \see map, at_key, insert_key, erase_key
     template<typename seq, typename key>
     using has_key = metal::contains<metal::keys<seq>, key>;
 }
diff --git a/include/metal/map/insert_key.hpp b/include/metal/map/insert_key.hpp
new file mode 100644
index 00000000..89370063
--- /dev/null
+++ b/include/metal/map/insert_key.hpp
@@ -0,0 +1,54 @@
+// Copyright Bruno Dutra 2015-2016
+// Distributed under the Boost Software License, Version 1.0.
+// See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt
+
+#ifndef METAL_MAP_INSERT_KEY_HPP
+#define METAL_MAP_INSERT_KEY_HPP
+
+#include <metal/config.hpp>
+
+#include <metal/map/has_key.hpp>
+#include <metal/list/append.hpp>
+#include <metal/pair/pair.hpp>
+#include <metal/number/if.hpp>
+
+namespace metal
+{
+    /// \ingroup map
+    ///
+    /// ### Description
+    /// Inserts a new entry in a \map.
+    ///
+    /// ### Usage
+    /// For any \map `m` and \values `k` and `v`
+    /// \code
+    ///     using result = metal::erase_key<m, k, v>;
+    /// \endcode
+    ///
+    /// \pre: `k` is not contained in `metal::keys<m>`
+    /// \returns: \map
+    /// \semantics:
+    ///     If `m` associates keys `k_1, ..., k_n` to values `v_1, ..., v_n`,
+    ///     then
+    ///     \code
+    ///         using result = metal::map<
+    ///             metal::pair<k_1, v_1>,
+    ///             ...,
+    ///             metal::pair<k_n, v_n>,
+    ///             metal::pair<k, v>
+    ///         >;
+    ///     \endcode
+    ///
+    /// ### Example
+    /// \snippet map.cpp insert_key
+    ///
+    /// ### See Also
+    /// \see map, has_key, at_key, erase_key
+    template<typename seq, typename key, typename val>
+    using insert_key = metal::if_<
+        metal::not_<metal::has_key<seq, key>>,
+        metal::append<seq, metal::pair<key, val>>
+    >;
+}
+
+#endif
diff --git a/include/metal/map/map.hpp b/include/metal/map/map.hpp
index 913992a1..f342b83f 100644
--- a/include/metal/map/map.hpp
+++ b/include/metal/map/map.hpp
@@ -12,11 +12,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
         struct _is_map;
     }
+    /// \endcond
 
     /// \ingroup map
     ///
@@ -44,7 +46,7 @@ namespace metal
     /// \snippet map.cpp is_map
     ///
     /// ### See Also
-    /// \see map
+    /// \see map, is_value, is_number, is_lambda, is_pair, is_list
     template<typename val>
     using is_map = typename detail::_is_map<val>::type;
 
@@ -53,6 +55,15 @@ namespace metal
     /// ### Description
     /// Constructs a \map out of a sequence of \pairs.
     ///
+    /// ### Usage
+    /// For any \pairs `pair_0, ..., pair_n-1`
+    /// \code
+    ///     using result = metal::map<pair_0, ..., pair_n-1>;
+    /// \endcode
+    ///
+    /// \pre: No two \pairs have the same key
+    /// \returns: \map
+    ///
     /// ### See Also
     /// \see is_map
     template<typename... pairs>
@@ -67,6 +78,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -84,6 +96,7 @@ namespace metal
             distinct<keys...>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/add.hpp b/include/metal/number/add.hpp
index 0dbfa38e..9ff326e9 100644
--- a/include/metal/number/add.hpp
+++ b/include/metal/number/add.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
         struct _add;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,15 +23,15 @@ namespace metal
     /// Computes the arithmetic addition of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::add<num_1, ..., num_n>;
+    ///     using result = metal::add<num_0, ..., num_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
     ///     \code
-    ///         using result = metal::number<num_1{} + ... + num_n{}>;
+    ///         using result = metal::number<num_0{} + ... + num_n-1{}>;
     ///     \endcode
     ///
     /// ### Example
@@ -50,6 +52,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
@@ -88,6 +91,7 @@ namespace metal
 
 #endif
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/and.hpp b/include/metal/number/and.hpp
index 66001b49..202d7304 100644
--- a/include/metal/number/and.hpp
+++ b/include/metal/number/and.hpp
@@ -19,15 +19,15 @@ namespace metal
     /// Computes the logical conjunction of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::and_<num_1, ..., num_n>;
+    ///     using result = metal::and_<num_0, ..., num_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
     ///     \code
-    ///         using result = metal::number<num_1{} && ... && num_n{}>;
+    ///         using result = metal::number<num_0{} && ... && num_n-1{}>;
     ///     \endcode
     ///
     /// ### Example
diff --git a/include/metal/number/div.hpp b/include/metal/number/div.hpp
index ce757ff2..b55f39fe 100644
--- a/include/metal/number/div.hpp
+++ b/include/metal/number/div.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
         struct _div;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,16 +23,17 @@ namespace metal
     /// Computes the quotient of the arithmetic division of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::div<num_1, ..., num_n>;
+    ///     using result = metal::div<num_0, ..., num_n-1>;
     /// \endcode
     ///
-    /// \pre: all \numbers in `[num_2, ..., num_n]` are nonzero
+    /// \pre: All \numbers in `num_1, ..., num_n-1` are nonzero
     /// \returns: \number
     /// \semantics:
+    ///     Equivalent to
     ///     \code
-    ///         using result = metal::number<num_1{} / ... / num_n{}>;
+    ///         using result = metal::number<num_0{} / ... / num_n-1{}>;
     ///     \endcode
     ///
     /// ### Example
@@ -51,6 +54,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
@@ -103,6 +107,7 @@ namespace metal
         {};
 #endif
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/enumerate.hpp b/include/metal/number/enumerate.hpp
index d16c0684..df20f04a 100644
--- a/include/metal/number/enumerate.hpp
+++ b/include/metal/number/enumerate.hpp
@@ -11,11 +11,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename, typename, typename>
         struct _enumerate;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -68,6 +70,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<int_... vs>
@@ -104,6 +107,7 @@ namespace metal
             >
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/greater.hpp b/include/metal/number/greater.hpp
index 5dc48ff5..56c45270 100644
--- a/include/metal/number/greater.hpp
+++ b/include/metal/number/greater.hpp
@@ -17,15 +17,15 @@ namespace metal
     /// Checks whether a \number is greater than another.
     ///
     /// ### Usage
-    /// For any \numbers `num_1` and `num_2`
+    /// For any \numbers `x` and `y`
     /// \code
-    ///     using result = metal::greater<num_1, num_2>;
+    ///     using result = metal::greater<x, y>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
     ///     \code
-    ///         using result = metal::number<(num_1{} > num_2{})>;
+    ///         using result = metal::number<(x{} > y{})>;
     ///     \endcode
     ///
     /// ### Example
diff --git a/include/metal/number/if.hpp b/include/metal/number/if.hpp
index 2aaa6a19..e277e27f 100644
--- a/include/metal/number/if.hpp
+++ b/include/metal/number/if.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename...>
         struct _if_;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,9 +23,14 @@ namespace metal
     /// A multi-clause conditional expression.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n` and \values `val_1, ..., val_n+1`
+    /// For any \numbers `num_0, ..., num_n-1` and \values `val_0, ..., val_n`
     /// \code
-    ///     using result = metal::if<num_1, val_1, ..., num_n, val_n, val_n+1>;
+    ///     using result = metal::if<
+    ///         num_0, val_0,
+    ///         ...,
+    ///         num_n-1, val_n-1,
+    ///         val_n
+    ///     >;
     /// \endcode
     ///
     /// \returns: \value
@@ -32,9 +39,9 @@ namespace metal
     ///     \code
     ///         using result = val_i;
     ///     \endcode
-    ///     otherwise, if `num_i{} == false` for all `i` in `[1, ..., n]`, then
+    ///     otherwise, if `num_i{} == false` for all `i` in `[0, n-1]`, then
     ///     \code
-    ///         using result = val_n+1;
+    ///         using result = val_n;
     ///     \endcode
     ///
     /// ### Example
@@ -50,6 +57,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename...>
@@ -73,6 +81,7 @@ namespace metal
             using type = then_;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/less.hpp b/include/metal/number/less.hpp
index c0b0c511..3ccb5c33 100644
--- a/include/metal/number/less.hpp
+++ b/include/metal/number/less.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename x, typename y>
         struct _less;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,15 +23,15 @@ namespace metal
     /// Checks whether a \number is less than another.
     ///
     /// ### Usage
-    /// For any \numbers `num_1` and `num_2`
+    /// For any \numbers `x` and `y`
     /// \code
-    ///     using result = metal::less<num_1, num_2>;
+    ///     using result = metal::less<x, y>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
     ///     \code
-    ///         using result = metal::number<(num_1{} < num_2{})>;
+    ///         using result = metal::number<(x{} < y{})>;
     ///     \endcode
     ///
     /// ### Example
@@ -45,6 +47,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename x, typename y>
@@ -56,6 +59,7 @@ namespace metal
             number<(x < y)>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/max.hpp b/include/metal/number/max.hpp
index 53066c2a..2c6ea879 100644
--- a/include/metal/number/max.hpp
+++ b/include/metal/number/max.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
         struct _max;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,14 +23,15 @@ namespace metal
     /// Computes the maximum of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::max<num_1, ..., num_n>;
+    ///     using result = metal::max<num_0, ..., num_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
-    ///     If `M` the maximum between all \numbers in `num_1, ..., num_n`, then
+    ///     If `M` the maximum between all \numbers in `num_0, ..., num_n-1`,
+    ///     then
     ///     \code
     ///         using result = M;
     ///     \endcode
@@ -51,6 +54,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
@@ -88,6 +92,7 @@ namespace metal
         {};
 #endif
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/min.hpp b/include/metal/number/min.hpp
index b7899939..173f2242 100644
--- a/include/metal/number/min.hpp
+++ b/include/metal/number/min.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
         struct _min;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,14 +23,15 @@ namespace metal
     /// Computes the minimum of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::min<num_1, ..., num_n>;
+    ///     using result = metal::min<num_0, ..., num_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
-    ///     If `m` the minimum between all \numbers in `num_1, ..., num_n`, then
+    ///     If `m` the minimum between all \numbers in `num_0, ..., num_n-1`,
+    ///     then
     ///     \code
     ///         using result = m;
     ///     \endcode
@@ -51,6 +54,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
@@ -88,6 +92,7 @@ namespace metal
         {};
 #endif
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/mod.hpp b/include/metal/number/mod.hpp
index e6a5a467..10f72e8e 100644
--- a/include/metal/number/mod.hpp
+++ b/include/metal/number/mod.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
         struct _mod;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,16 +23,17 @@ namespace metal
     /// Computes the remainder of the arithmetic division of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::mod<num_1, ..., num_n>;
+    ///     using result = metal::mod<num_0, ..., num_n-1>;
     /// \endcode
     ///
-    /// \pre: all \numbers in `[num_2, ..., num_n]` are nonzero
+    /// \pre: All \numbers in `num_1, ..., num_n-1` are nonzero
     /// \returns: \number
     /// \semantics:
+    ///     Equivalent to
     ///     \code
-    ///         using result = metal::number<num_1{} % ... % num_n{}>;
+    ///         using result = metal::number<num_0{} % ... % num_n-1{}>;
     ///     \endcode
     ///
     /// ### Example
@@ -51,6 +54,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
@@ -103,6 +107,7 @@ namespace metal
         {};
 #endif
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/mul.hpp b/include/metal/number/mul.hpp
index 4f7e8679..0ed1569e 100644
--- a/include/metal/number/mul.hpp
+++ b/include/metal/number/mul.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
         struct _mul;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,15 +23,15 @@ namespace metal
     /// Computes the arithmetic multiplication of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::mul<num_1, ..., num_n>;
+    ///     using result = metal::mul<num_0, ..., num_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
     ///     \code
-    ///         using result = metal::number<num_1{} * ... * num_n{}>;
+    ///         using result = metal::number<num_0{} * ... * num_n-1{}>;
     ///     \endcode
     ///
     /// ### Example
@@ -50,6 +52,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
@@ -87,6 +90,7 @@ namespace metal
         {};
 #endif
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/number.hpp b/include/metal/number/number.hpp
index d902fef2..aef9c875 100644
--- a/include/metal/number/number.hpp
+++ b/include/metal/number/number.hpp
@@ -12,6 +12,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -22,6 +23,7 @@ namespace metal
         template<int_... vs>
         struct _numbers;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -49,7 +51,7 @@ namespace metal
     /// \snippet number.cpp is_number
     ///
     /// ### See Also
-    /// \see number, true_, false_
+    /// \see number, is_value, is_lambda, is_pair, is_list, is_map
     template<typename val>
     using is_number = typename detail::_is_number<val>::type;
 
@@ -67,8 +69,16 @@ namespace metal
     /// ### Description
     /// Constructs a \number out of an integral value.
     ///
+    /// ### Usage
+    /// For any integral value `N`
+    /// \code
+    ///     using result = metal::number<N>;
+    /// \endcode
+    ///
+    /// \returns: \number
+    ///
     /// ### See Also
-    /// \see int_, is_number
+    /// \see int_, true_, false_, is_number
     template<int_ v>
     using number = std::integral_constant<metal::int_, v>;
 
@@ -113,6 +123,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -131,6 +142,7 @@ namespace metal
             using type = list<number<vs>...>;
         };
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/or.hpp b/include/metal/number/or.hpp
index 25752271..ac5abcbe 100644
--- a/include/metal/number/or.hpp
+++ b/include/metal/number/or.hpp
@@ -19,15 +19,15 @@ namespace metal
     /// Computes the logical disjunction of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::or_<num_1, ..., num_n>;
+    ///     using result = metal::or_<num_0, ..., num_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
     ///     \code
-    ///         using result = metal::number<num_1{} || ... || num_n{}>;
+    ///         using result = metal::number<num_0{} || ... || num_n-1{}>;
     ///     \endcode
     ///
     /// ### Example
diff --git a/include/metal/number/pow.hpp b/include/metal/number/pow.hpp
index 9e60b539..14d353b3 100644
--- a/include/metal/number/pow.hpp
+++ b/include/metal/number/pow.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
         struct _pow;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,24 +23,22 @@ namespace metal
     /// Computes the arithmetic exponentiation of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::pow<num_1, ..., num_n>;
+    ///     using result = metal::pow<num_0, ..., num_n-1>;
     /// \endcode
     ///
-    /// \pre: `num_1{} ** ... ** num_m-1{}` is nonzero for all
+    /// \pre: `metal::pow<num_0, ..., num_m-1> != metal::number<0>` for all
     /// negative `num_m`
     /// \returns: \number
     /// \semantics:
+    ///     Equivalent to
     ///     \code
-    ///         using result = metal::number<num_1{} ** ... ** num_n{}>;
+    ///         using result = metal::number<num_0{} ** ... ** num_n-1{}>;
     ///     \endcode
-    ///     \note{
-    ///         Borrowing from Fortran, `x ** y` should be understood as
-    ///         `x` raised to the power of `y`.
-    ///     }
+    ///     Where the notation `x**y` stands for `x` raised to the power of `y`
     ///     \warning{
-    ///         `x ** y` is always null for `y < 0` and `|x| > 1`
+    ///         `x**y` is always null for `y < 0` and `|x| > 1`
     ///         due to inherent limitations of integer arithmetic.
     ///     }
     ///
@@ -58,6 +58,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename base, typename exp, typename ret = number<1>>
@@ -107,6 +108,7 @@ namespace metal
             _fold_left<numbers<y, tail...>, number<x>, lambda<pow>>
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/number/sub.hpp b/include/metal/number/sub.hpp
index 7c7128b6..216f5936 100644
--- a/include/metal/number/sub.hpp
+++ b/include/metal/number/sub.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
         struct _sub;
     }
+    /// \endcond
 
     /// \ingroup number
     ///
@@ -21,15 +23,15 @@ namespace metal
     /// Computes the arithmetic subtraction of \numbers.
     ///
     /// ### Usage
-    /// For any \numbers `num_1, ..., num_n`
+    /// For any \numbers `num_0, ..., num_n-1`
     /// \code
-    ///     using result = metal::sub<num_1, ..., num_n>;
+    ///     using result = metal::sub<num_0, ..., num_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
     ///     \code
-    ///         using result = metal::number<num_1{} - ... - num_n{}>;
+    ///         using result = metal::number<num_0{} - ... - num_n-1{}>;
     ///     \endcode
     ///
     /// ### Example
@@ -50,6 +52,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename head, typename... tail>
@@ -87,6 +90,7 @@ namespace metal
         {};
 #endif
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/pair/first.hpp b/include/metal/pair/first.hpp
index 39d5379c..851d34b7 100644
--- a/include/metal/pair/first.hpp
+++ b/include/metal/pair/first.hpp
@@ -16,7 +16,7 @@ namespace metal
     /// \ingroup pair
     ///
     /// ### Description
-    /// Returns the first element of a \pair.
+    /// Retrieves the first element of a \pair.
     ///
     /// ### Usage
     /// For any \pair `p`
@@ -26,9 +26,9 @@ namespace metal
     ///
     /// \returns: \value
     /// \semantics:
-    ///     If `p` contains \values `x` and `y` in that order, then
+    ///     If `p` contains \values `p_0` and `p_1` in that order, then
     ///     \code
-    ///         using result = x;
+    ///         using result = p_0;
     ///     \endcode
     ///
     /// ### Example
diff --git a/include/metal/pair/pair.hpp b/include/metal/pair/pair.hpp
index 1b09c1f1..3b724d07 100644
--- a/include/metal/pair/pair.hpp
+++ b/include/metal/pair/pair.hpp
@@ -11,11 +11,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
         struct _is_pair;
     }
+    /// \endcond
 
     /// \ingroup pair
     ///
@@ -43,7 +45,7 @@ namespace metal
     /// \snippet pair.cpp is_pair
     ///
     /// ### See Also
-    /// \see pair
+    /// \see pair, is_value, is_number, is_lambda, is_list, is_map
     template<typename val>
     using is_pair = typename detail::_is_pair<val>::type;
 
@@ -52,6 +54,14 @@ namespace metal
     /// ### Description
     /// Constructs a \pair out of a pair of \values.
     ///
+    /// ### Usage
+    /// For any pair of \values `x` and `y`
+    /// \code
+    ///     using result = metal::pair<x, y>;
+    /// \endcode
+    ///
+    /// \returns: \pair
+    ///
     /// ### See Also
     /// \see is_pair
     template<typename x, typename y>
@@ -62,6 +72,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -74,6 +85,7 @@ namespace metal
             true_
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/pair/second.hpp b/include/metal/pair/second.hpp
index 72533cda..f53d043c 100644
--- a/include/metal/pair/second.hpp
+++ b/include/metal/pair/second.hpp
@@ -16,7 +16,7 @@ namespace metal
     /// \ingroup pair
     ///
     /// ### Description
-    /// Returns the second element of a \pair.
+    /// Retrieves the second element of a \pair.
     ///
     /// ### Usage
     /// For any \pair `p`
@@ -26,9 +26,9 @@ namespace metal
     ///
     /// \returns: \value
     /// \semantics:
-    ///     If `p` contains \values `x` and `y` in that order, then
+    ///     If `p` contains \values `p_0` and `p_1` in that order, then
     ///     \code
-    ///         using result = y;
+    ///         using result = p_1;
     ///     \endcode
     ///
     /// ### Example
diff --git a/include/metal/value/distinct.hpp b/include/metal/value/distinct.hpp
index 53a996f6..6913984e 100644
--- a/include/metal/value/distinct.hpp
+++ b/include/metal/value/distinct.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename... vals>
         struct _distinct;
     }
+    /// \endcond
 
     /// \ingroup value
     ///
@@ -21,14 +23,14 @@ namespace metal
     /// Checks whether no \values are identical.
     ///
     /// ### Usage
-    /// For any \values `val_1, ..., val_n`
+    /// For any \values `val_0, ..., val_n-1`
     /// \code
-    ///     using result = metal::distinct<val_1, ..., val_n>;
+    ///     using result = metal::distinct<val_0, ..., val_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
-    ///     If at least two \values in `val_1, ..., val_n` are identical to
+    ///     If at least two \values in `val_0, ..., val_n-1` are identical to
     ///     each other, then
     ///     \code
     ///         using result = metal::false_;
@@ -56,6 +58,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename, typename base>
@@ -92,6 +95,7 @@ namespace metal
             decltype(_distinct_impl<inherit<value<vals>...>, value<vals>...>(0))
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/value/same.hpp b/include/metal/value/same.hpp
index 1b8f7ff0..7ae16f9a 100644
--- a/include/metal/value/same.hpp
+++ b/include/metal/value/same.hpp
@@ -9,11 +9,13 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename... vals>
         struct _same;
     }
+    /// \endcond
 
     /// \ingroup value
     ///
@@ -21,15 +23,15 @@ namespace metal
     /// Checks whether all \values are identical.
     ///
     /// ### Usage
-    /// For any \values `val_1, ..., val_n`
+    /// For any \values `val_0, ..., val_n-1`
     /// \code
-    ///     using result = metal::same<val_1, ..., val_n>;
+    ///     using result = metal::same<val_0, ..., val_n-1>;
     /// \endcode
     ///
     /// \returns: \number
     /// \semantics:
-    ///     If at least two \values in `val_1, ..., val_n` are not identical to
-    ///     each other, then
+    ///     If at least two \values in `val_0, ..., val_n-1` are not identical
+    ///     to each other, then
     ///     \code
     ///         using result = metal::false_;
     ///     \endcode
@@ -52,6 +54,7 @@ namespace metal
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         template<typename...>
@@ -89,6 +92,7 @@ namespace metal
             true_
         {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/include/metal/value/value.hpp b/include/metal/value/value.hpp
index 0bf3a827..bf779c09 100644
--- a/include/metal/value/value.hpp
+++ b/include/metal/value/value.hpp
@@ -11,6 +11,7 @@
 
 namespace metal
 {
+    /// \cond
     namespace detail
     {
         struct na;
@@ -18,6 +19,7 @@ namespace metal
         template<typename val = na>
         struct value;
     }
+    /// \endcond
 
     /// \ingroup value
     ///
@@ -43,7 +45,7 @@ namespace metal
     /// \snippet value.cpp is_value
     ///
     /// ### See Also
-    /// \see value, nil
+    /// \see value, nil, is_number, is_lambda, is_pair, is_list, is_map
     template<typename val>
     using is_value = metal::true_;
 
@@ -53,8 +55,8 @@ namespace metal
     /// Constructs a \value that is guaranteed not to be a \number, or a
     /// \lambda or a \list, out of any other \value.
     ///
-    /// The original \value may be retrieved back by naming its nested typename
-    /// `::type`, unless `metal::value` is [empty](\ref nil), in which case it
+    /// The original \value may be retrieved back by naming the nested typename
+    /// `type`, unless `metal::value` is [empty](\ref nil), in which case `type`
     /// is undefined.
     ///
     /// \tip{Use `metal::value` to prevent undesired template pattern matching.}
@@ -105,6 +107,7 @@ namespace metal
     /// \see is_value, value
     using nil = metal::value<>;
 
+    /// \cond
     namespace detail
     {
         template<typename val>
@@ -116,6 +119,7 @@ namespace metal
         template<>
         struct value<na> {};
     }
+    /// \endcond
 }
 
 #endif
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index e930e258..3a86b52b 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -2,7 +2,6 @@
 # Distributed under the Boost Software License, Version 1.0.
 # See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt
 
-include_directories("${METAL_INCLUDE_DIR}")
 include_directories("${CMAKE_CURRENT_SOURCE_DIR}/include/")
 
 add_definitions(-DEXPECTED_METAL_MAJOR=${METAL_MAJOR})
diff --git a/test/src/metal.cpp b/test/src/metal.cpp
index 38cfa438..227de7e4 100644
--- a/test/src/metal.cpp
+++ b/test/src/metal.cpp
@@ -44,6 +44,7 @@
     CHECK((metal::second<metal::transpose<MAP(INC(M))>>), (metal::values<MAP(INC(M))>)); \
     CHECK((metal::at<MAP(INF), metal::order<MAP(INF), NUMBER(N)>>), (PAIR(N))); \
     CHECK((metal::has_key<metal::erase_key<MAP(INF), NUMBER(M)>, NUMBER(N)>), (BOOL(M != N))); \
+    CHECK((metal::insert_key<MAP(M), NUMBER(M), VALUE(N)>), (metal::append<MAP(M), metal::pair<NUMBER(M), VALUE(N)>>)); \
 /**/
 
 GEN(MATRIX)
diff --git a/test/src/metal/map/insert_key.cpp b/test/src/metal/map/insert_key.cpp
new file mode 100644
index 00000000..e9a67338
--- /dev/null
+++ b/test/src/metal/map/insert_key.cpp
@@ -0,0 +1,67 @@
+// Copyright Bruno Dutra 2015-2016
+// Distributed under the Boost Software License, Version 1.0.
+// See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt
+
+#include <metal/map/insert_key.hpp>
+#include <metal/list/list.hpp>
+#include <metal/lambda/lambda.hpp>
+#include <metal/lambda/invoke.hpp>
+#include <metal/number/number.hpp>
+
+#include "test.hpp"
+
+#define MATRIX(M, N) \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, VALUE(M), VALUE(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, VALUE(M), NUMBER(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, VALUE(M), PAIR(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, VALUE(M), LIST(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, VALUE(M), MAP(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, VALUE(M), LAMBDA(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, VALUE(M), LAMBDA(_), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, NUMBER(M), VALUE(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, NUMBER(M), NUMBER(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, NUMBER(M), PAIR(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, NUMBER(M), LIST(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, NUMBER(M), MAP(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, NUMBER(M), LAMBDA(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, NUMBER(M), LAMBDA(_), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, PAIR(M), VALUE(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, PAIR(M), NUMBER(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, PAIR(M), PAIR(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, PAIR(M), LIST(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, PAIR(M), MAP(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, PAIR(M), LAMBDA(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, PAIR(M), LAMBDA(_), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LIST(M), VALUE(N), VALUE(M)>), (BOOL(!M))); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LIST(M), NUMBER(N), VALUE(M)>), (BOOL(!M))); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LIST(M), PAIR(N), VALUE(M)>), (BOOL(!M))); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LIST(M), LIST(N), VALUE(M)>), (BOOL(!M))); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LIST(M), MAP(N), VALUE(M)>), (BOOL(!M))); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LIST(M), LAMBDA(N), VALUE(M)>), (BOOL(!M))); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LIST(M), LAMBDA(_), VALUE(M)>), (BOOL(!M))); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, MAP(M), VALUE(N), VALUE(M)>), (TRUE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, MAP(M), NUMBER(N), VALUE(M)>), (BOOL(M <= N))); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, MAP(M), PAIR(N), VALUE(M)>), (TRUE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, MAP(M), LIST(N), VALUE(M)>), (TRUE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, MAP(M), MAP(N), VALUE(M)>), (TRUE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, MAP(M), LAMBDA(N), VALUE(M)>), (TRUE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, MAP(M), LAMBDA(_), VALUE(M)>), (TRUE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(M), VALUE(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(M), NUMBER(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(M), PAIR(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(M), LIST(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(M), MAP(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(M), LAMBDA(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(M), LAMBDA(_), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(_), VALUE(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(_), NUMBER(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(_), PAIR(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(_), LIST(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(_), MAP(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(_), LAMBDA(N), VALUE(M)>), (FALSE)); \
+    CHECK((metal::is_invocable<metal::lambda<metal::insert_key>, LAMBDA(_), LAMBDA(_), VALUE(M)>), (FALSE)); \
+    CHECK((metal::insert_key<MAP(M), NUMBER(M), VALUE(N)>), (metal::list<PAIRS(M) COMMA(M) metal::pair<NUMBER(M), VALUE(N)>>)); \
+/**/
+
+GEN(MATRIX)
+