Remove old docstrings

include/tl/expected.hpp

@@ -1,6 +1,8 @@
 ///
 // expected - An implementation of std::expected with extensions
-// Written in 2017 by Simon Brand (@TartanLlama)
+// Written in 2017 by Simon Brand (@TartanLlama, simonrbrand@gmail.com)
+//
+// Documentation available at http://tl.tartanllama.xyz/
 //
 // To the extent possible under law, the author(s) have dedicated all
 // copyright and related and neighboring rights to this software to the
@@ -28,7 +30,6 @@
 #endif
 
 #if (defined(_MSC_VER) && _MSC_VER == 1900)
-/// \exclude
 #define TL_EXPECTED_MSVC2015
 #define TL_EXPECTED_MSVC2015_CONSTEXPR
 #else
@@ -37,38 +38,31 @@
 
 #if (defined(__GNUC__) && __GNUC__ == 4 && __GNUC_MINOR__ <= 9 &&              \
      !defined(__clang__))
-/// \exclude
 #define TL_EXPECTED_GCC49
 #endif
 
 #if (defined(__GNUC__) && __GNUC__ == 5 && __GNUC_MINOR__ <= 4 &&              \
      !defined(__clang__))
-/// \exclude
 #define TL_EXPECTED_GCC54
 #endif
 
 #if (defined(__GNUC__) && __GNUC__ == 5 && __GNUC_MINOR__ <= 5 &&              \
      !defined(__clang__))
-/// \exclude
 #define TL_EXPECTED_GCC55
 #endif
 
 #if (defined(__GNUC__) && __GNUC__ == 4 && __GNUC_MINOR__ <= 9 &&              \
      !defined(__clang__))
 // GCC < 5 doesn't support overloading on const&& for member functions
-/// \exclude
-#define TL_EXPECTED_NO_CONSTRR
 
+#define TL_EXPECTED_NO_CONSTRR
 // GCC < 5 doesn't support some standard C++11 type traits
-/// \exclude
 #define TL_EXPECTED_IS_TRIVIALLY_COPY_CONSTRUCTIBLE(T)                         \
   std::has_trivial_copy_constructor<T>
-/// \exclude
 #define TL_EXPECTED_IS_TRIVIALLY_COPY_ASSIGNABLE(T)                            \
   std::has_trivial_copy_assign<T>
 
 // This one will be different for GCC 5.7 if it's ever supported
-/// \exclude
 #define TL_EXPECTED_IS_TRIVIALLY_DESTRUCTIBLE(T)                               \
   std::is_trivially_destructible<T>
 
@@ -97,19 +91,15 @@ namespace tl {
   std::is_trivially_copy_assignable<T>
 #define TL_EXPECTED_IS_TRIVIALLY_DESTRUCTIBLE(T) std::is_trivially_destructible<T>
 #else
-/// \exclude
 #define TL_EXPECTED_IS_TRIVIALLY_COPY_CONSTRUCTIBLE(T)                         \
   std::is_trivially_copy_constructible<T>
-/// \exclude
 #define TL_EXPECTED_IS_TRIVIALLY_COPY_ASSIGNABLE(T)                            \
   std::is_trivially_copy_assignable<T>
-/// \exclude
 #define TL_EXPECTED_IS_TRIVIALLY_DESTRUCTIBLE(T)                               \
   std::is_trivially_destructible<T>
 #endif
 
 #if __cplusplus > 201103L
-/// \exclude
 #define TL_EXPECTED_CXX14
 #endif
 
@@ -121,10 +111,8 @@ namespace tl {
 
 #if (__cplusplus == 201103L || defined(TL_EXPECTED_MSVC2015) ||                \
      defined(TL_EXPECTED_GCC49))
-/// \exclude
 #define TL_EXPECTED_11_CONSTEXPR
 #else
-/// \exclude
 #define TL_EXPECTED_11_CONSTEXPR constexpr
 #endif
 
@@ -133,18 +121,14 @@ template <class T, class E> class expected;
 
 #ifndef TL_MONOSTATE_INPLACE_MUTEX
 #define TL_MONOSTATE_INPLACE_MUTEX
-/// \brief Used to represent an expected with no data
 class monostate {};
 
-/// \brief A tag type to tell expected to construct its value in-place
 struct in_place_t {
   explicit in_place_t() = default;
 };
-/// \brief A tag to tell expected to construct its value in-place
 static constexpr in_place_t in_place{};
 #endif
 
-/// Used as a wrapper to store the unexpected value
 template <class E> class unexpected {
 public:
   static_assert(!std::is_same<E, void>::value, "E must not be void");
@@ -154,7 +138,6 @@ public:
 
   constexpr explicit unexpected(E &&e) : m_val(std::move(e)) {}
 
-  /// Returns the contained value
   constexpr const E &value() const & { return m_val; }
   TL_EXPECTED_11_CONSTEXPR E &value() & { return m_val; }
   TL_EXPECTED_11_CONSTEXPR E &&value() && { return std::move(m_val); }
@@ -164,7 +147,6 @@ private:
   E m_val;
 };
 
-/// Compares two unexpected objects
 template <class E>
 constexpr bool operator==(const unexpected<E> &lhs, const unexpected<E> &rhs) {
   return lhs.value() == rhs.value();
@@ -190,20 +172,16 @@ constexpr bool operator>=(const unexpected<E> &lhs, const unexpected<E> &rhs) {
   return lhs.value() >= rhs.value();
 }
 
-/// Create an `unexpected` from `e`, deducing the return type
 template <class E>
 unexpected<typename std::decay<E>::type> make_unexpected(E &&e) {
   return unexpected<typename std::decay<E>::type>(std::forward<E>(e));
 }
 
-/// A tag type to tell expected to construct the unexpected value
 struct unexpect_t {
   unexpect_t() = default;
 };
-/// A tag to tell expected to construct the unexpected value
 static constexpr unexpect_t unexpect{};
 
-/// \exclude
 namespace detail {
 template<typename E>
 [[noreturn]] TL_EXPECTED_11_CONSTEXPR void throw_exception(E &&e) {
@@ -426,7 +404,6 @@ using is_move_assignable_or_void =
 
 } // namespace detail
 
-/// \exclude
 namespace detail {
 struct no_init_t {};
 static constexpr no_init_t no_init{};
@@ -1276,65 +1253,33 @@ public:
 
 #if defined(TL_EXPECTED_CXX14) && !defined(TL_EXPECTED_GCC49) &&               \
     !defined(TL_EXPECTED_GCC54) && !defined(TL_EXPECTED_GCC55)
-  /// \group and_then
-  /// Carries out some operation which returns an expected on the stored object
-  /// if there is one. \requires `std::invoke(std::forward<F>(f), value())`
-  /// returns an `expected<U>` for some `U`. \returns Let `U` be the result
-  /// of `std::invoke(std::forward<F>(f), value())`. Returns an
-  /// `expected<U>`. The return value is empty if `*this` is empty,
-  /// otherwise the return value of `std::invoke(std::forward<F>(f), value())`
-  /// is returned.
-  /// \synopsis template <class F>\nconstexpr auto and_then(F &&f) &;
   template <class F> TL_EXPECTED_11_CONSTEXPR auto and_then(F &&f) & {
     return and_then_impl(*this, std::forward<F>(f));
   }
-
-  /// \group and_then
-  /// \synopsis template <class F>\nconstexpr auto and_then(F &&f) &&;
   template <class F> TL_EXPECTED_11_CONSTEXPR auto and_then(F &&f) && {
     return and_then_impl(std::move(*this), std::forward<F>(f));
   }
-
-  /// \group and_then
-  /// \synopsis template <class F>\nconstexpr auto and_then(F &&f) const &;
   template <class F> constexpr auto and_then(F &&f) const & {
     return and_then_impl(*this, std::forward<F>(f));
   }
 
 #ifndef TL_EXPECTED_NO_CONSTRR
-  /// \group and_then
-  /// \synopsis template <class F>\nconstexpr auto and_then(F &&f) const &&;
   template <class F> constexpr auto and_then(F &&f) const && {
     return and_then_impl(std::move(*this), std::forward<F>(f));
   }
 #endif
 
 #else
-  /// \group and_then
-  /// Carries out some operation which returns an expected on the stored object
-  /// if there is one. \requires `std::invoke(std::forward<F>(f), value())`
-  /// returns an `expected<U>` for some `U`. \returns Let `U` be the result
-  /// of `std::invoke(std::forward<F>(f), value())`. Returns an
-  /// `expected<U>`. The return value is empty if `*this` is empty,
-  /// otherwise the return value of `std::invoke(std::forward<F>(f), value())`
-  /// is returned.
-  /// \synopsis template <class F>\nconstexpr auto and_then(F &&f) &;
   template <class F>
   TL_EXPECTED_11_CONSTEXPR auto
   and_then(F &&f) & -> decltype(and_then_impl(std::declval<expected&>(), std::forward<F>(f))) {
     return and_then_impl(*this, std::forward<F>(f));
   }
-
-  /// \group and_then
-  /// \synopsis template <class F>\nconstexpr auto and_then(F &&f) &&;
   template <class F>
   TL_EXPECTED_11_CONSTEXPR auto and_then(F &&f) && -> decltype(
       and_then_impl(std::declval<expected&&>(), std::forward<F>(f))) {
     return and_then_impl(std::move(*this), std::forward<F>(f));
   }
-
-  /// \group and_then
-  /// \synopsis template <class F>\nconstexpr auto and_then(F &&f) const &;
   template <class F>
   constexpr auto and_then(F &&f) const & -> decltype(
       and_then_impl(std::declval<expected const&>(), std::forward<F>(f))) {
@@ -1342,8 +1287,6 @@ public:
   }
 
 #ifndef TL_EXPECTED_NO_CONSTRR
-  /// \group and_then
-  /// \synopsis template <class F>\nconstexpr auto and_then(F &&f) const &&;
   template <class F>
   constexpr auto and_then(F &&f) const && -> decltype(
       and_then_impl(std::declval<expected const&&>(), std::forward<F>(f))) {
@@ -1354,7 +1297,6 @@ public:
 
 #if defined(TL_EXPECTED_CXX14) && !defined(TL_EXPECTED_GCC49) &&               \
     !defined(TL_EXPECTED_GCC54) && !defined(TL_EXPECTED_GCC55)
-  /// Carries out some operation on the stored object if there is one.
     template <class F> TL_EXPECTED_11_CONSTEXPR auto map(F &&f) & {
     return expected_map_impl(*this, std::forward<F>(f));
   }
@@ -1368,7 +1310,6 @@ public:
     return expected_map_impl(std::move(*this), std::forward<F>(f));
   }
 #else
-  /// Carries out some operation on the stored object if there is one.
   template <class F>
   TL_EXPECTED_11_CONSTEXPR decltype(
       expected_map_impl(std::declval<expected &>(), std::declval<F &&>()))
@@ -1400,7 +1341,6 @@ public:
 
 #if defined(TL_EXPECTED_CXX14) && !defined(TL_EXPECTED_GCC49) &&               \
     !defined(TL_EXPECTED_GCC54) && !defined(TL_EXPECTED_GCC55)
-  /// Carries out some operation on the stored object if there is one.
     template <class F> TL_EXPECTED_11_CONSTEXPR auto transform(F &&f) & {
     return expected_map_impl(*this, std::forward<F>(f));
   }
@@ -1414,7 +1354,6 @@ public:
     return expected_map_impl(std::move(*this), std::forward<F>(f));
   }
 #else
-  /// Carries out some operation on the stored object if there is one.
     template <class F>
   TL_EXPECTED_11_CONSTEXPR decltype(
       expected_map_impl(std::declval<expected &>(), std::declval<F &&>()))
@@ -1446,67 +1385,31 @@ public:
 
 #if defined(TL_EXPECTED_CXX14) && !defined(TL_EXPECTED_GCC49) &&               \
     !defined(TL_EXPECTED_GCC54) && !defined(TL_EXPECTED_GCC55)
-  /// \brief Carries out some operation on the stored unexpected object if there
-  /// is one.
-  /// \returns Let `U` be the result of `std::invoke(std::forward<F>(f),
-  /// value())`. If `U` is `void`, returns an `expected<T,monostate>`, otherwise
-  /// returns an `expected<T,U>`. If `*this` has an expected
-  /// value, the result is `*this`, otherwise an `expected<T,U>` is constructed
-  /// from `make_unexpected(std::invoke(std::forward<F>(f), value()))` and is
-  /// returned.
-  ///
-  /// \group map_error
-  /// \synopsis template <class F> constexpr auto map_error(F &&f) &;
   template <class F> TL_EXPECTED_11_CONSTEXPR auto map_error(F &&f) & {
     return map_error_impl(*this, std::forward<F>(f));
   }
-
-  /// \group map_error
-  /// \synopsis template <class F> constexpr auto map_error(F &&f) &&;
   template <class F> TL_EXPECTED_11_CONSTEXPR auto map_error(F &&f) && {
     return map_error_impl(std::move(*this), std::forward<F>(f));
   }
-
-  /// \group map_error
-  /// \synopsis template <class F> constexpr auto map_error(F &&f) const &;
   template <class F> constexpr auto map_error(F &&f) const & {
     return map_error_impl(*this, std::forward<F>(f));
   }
-
-  /// \group map_error
-  /// \synopsis template <class F> constexpr auto map_error(F &&f) const &&;
   template <class F> constexpr auto map_error(F &&f) const && {
     return map_error_impl(std::move(*this), std::forward<F>(f));
   }
 #else
-  /// \brief Carries out some operation on the stored unexpected object if there
-  /// is one.
-  /// \returns Let `U` be the result of `std::invoke(std::forward<F>(f),
-  /// value())`. Returns an `expected<T,U>`. If `*this` has an expected
-  /// value, the result is `*this`, otherwise an `expected<T,U>` is constructed
-  /// from `make_unexpected(std::invoke(std::forward<F>(f), value()))` and is
-  /// returned.
-  ///
-  /// \group map_error
-  /// \synopsis template <class F> constexpr auto map_error(F &&f) &;
   template <class F>
   TL_EXPECTED_11_CONSTEXPR decltype(map_error_impl(std::declval<expected &>(),
                                                    std::declval<F &&>()))
   map_error(F &&f) & {
     return map_error_impl(*this, std::forward<F>(f));
   }
-
-  /// \group map_error
-  /// \synopsis template <class F> constexpr auto map_error(F &&f) &&;
   template <class F>
   TL_EXPECTED_11_CONSTEXPR decltype(map_error_impl(std::declval<expected &&>(),
                                                    std::declval<F &&>()))
   map_error(F &&f) && {
     return map_error_impl(std::move(*this), std::forward<F>(f));
   }
-
-  /// \group map_error
-  /// \synopsis template <class F> constexpr auto map_error(F &&f) const &;
   template <class F>
   constexpr decltype(map_error_impl(std::declval<const expected &>(),
                                     std::declval<F &&>()))
@@ -1515,8 +1418,6 @@ public:
   }
 
 #ifndef TL_EXPECTED_NO_CONSTRR
-  /// \group map_error
-  /// \synopsis template <class F> constexpr auto map_error(F &&f) const &&;
   template <class F>
   constexpr decltype(map_error_impl(std::declval<const expected &&>(),
                                     std::declval<F &&>()))
@@ -1525,15 +1426,6 @@ public:
   }
 #endif
 #endif
-
-  /// \brief Calls `f` if the expectd is in the unexpected state
-  /// \requires `F` is invokable with `E`, and `std::invoke_result_t<F>`
-  /// must be void or convertible to `expcted<T,E>`.
-  /// \effects If `*this` has a value, returns `*this`.
-  /// Otherwise, if `f` returns `void`, calls `std::forward<F>(f)(E)` and returns
-  /// `std::nullopt`. Otherwise, returns `std::forward<F>(f)(E)`.
-  ///
-  /// \group or_else
   template <class F> expected TL_EXPECTED_11_CONSTEXPR or_else(F &&f) & {
     return or_else_impl(*this, std::forward<F>(f));
   }
@@ -1571,8 +1463,6 @@ public:
       : impl_base(in_place, il, std::forward<Args>(args)...),
         ctor_base(detail::default_constructor_tag{}) {}
 
-  /// \group unexpected_ctor
-  /// \synopsis EXPLICIT constexpr expected(const unexpected<G> &e);
   template <class G = E,
             detail::enable_if_t<std::is_constructible<E, const G &>::value> * =
                 nullptr,
@@ -1582,7 +1472,6 @@ public:
       : impl_base(unexpect, e.value()),
         ctor_base(detail::default_constructor_tag{}) {}
 
-  /// \exclude
     template <
       class G = E,
       detail::enable_if_t<std::is_constructible<E, const G &>::value> * =
@@ -1592,8 +1481,6 @@ public:
       : impl_base(unexpect, e.value()),
         ctor_base(detail::default_constructor_tag{}) {}
 
-  /// \group unexpected_ctor
-  /// \synopsis EXPLICIT constexpr expected(unexpected<G> &&e);
   template <
       class G = E,
       detail::enable_if_t<std::is_constructible<E, G &&>::value> * = nullptr,
@@ -1603,7 +1490,6 @@ public:
       : impl_base(unexpect, std::move(e.value())),
         ctor_base(detail::default_constructor_tag{}) {}
 
-  /// \exclude
     template <
       class G = E,
       detail::enable_if_t<std::is_constructible<E, G &&>::value> * = nullptr,
@@ -1620,7 +1506,6 @@ public:
       : impl_base(unexpect, std::forward<Args>(args)...),
         ctor_base(detail::default_constructor_tag{}) {}
 
-  /// \exclude
     template <class U, class... Args,
             detail::enable_if_t<std::is_constructible<
                 E, std::initializer_list<U> &, Args &&...>::value> * = nullptr>
@@ -1644,7 +1529,6 @@ public:
     }
   }
 
-  /// \exclude
     template <class U, class G,
             detail::enable_if_t<(std::is_convertible<U const &, T>::value &&
                                  std::is_convertible<G const &, E>::value)> * =
@@ -1674,7 +1558,6 @@ public:
     }            
   }
 
-  /// \exclude
     template <
       class U, class G,
       detail::enable_if_t<(std::is_convertible<U &&, T>::value &&
@@ -1696,7 +1579,6 @@ public:
   explicit TL_EXPECTED_MSVC2015_CONSTEXPR expected(U &&v)
       : expected(in_place, std::forward<U>(v)) {}
 
-  /// \exclude
     template <
       class U = T,
       detail::enable_if_t<std::is_convertible<U &&, T>::value> * = nullptr,
@@ -1728,7 +1610,6 @@ public:
     return *this;
   }
 
-  /// \exclude
     template <
       class U = T, class G = T,
       detail::enable_if_t<!std::is_nothrow_constructible<T, U &&>::value> * =
@@ -1807,7 +1688,6 @@ public:
     }
   }
 
-  /// \exclude
     template <class... Args, detail::enable_if_t<!std::is_nothrow_constructible<
                                T, Args &&...>::value> * = nullptr>
   void emplace(Args &&... args) {
@@ -1846,7 +1726,6 @@ public:
     }
   }
 
-  /// \exclude
     template <class U, class... Args,
             detail::enable_if_t<!std::is_nothrow_constructible<
                 T, std::initializer_list<U> &, Args &&...>::value> * = nullptr>
@@ -1983,50 +1862,33 @@ public:
     }
   }
 
-  /// \returns a pointer to the stored value
-  /// \requires a value is stored
-  /// \group pointer
   constexpr const T *operator->() const { return valptr(); }
-  /// \group pointer
   TL_EXPECTED_11_CONSTEXPR T *operator->() { return valptr(); }
 
-  /// \returns the stored value
-  /// \requires a value is stored
-  /// \group deref
   template <class U = T,
             detail::enable_if_t<!std::is_void<U>::value> * = nullptr>
   constexpr const U &operator*() const & {
     return val();
   }
-  /// \group deref
   template <class U = T,
             detail::enable_if_t<!std::is_void<U>::value> * = nullptr>
   TL_EXPECTED_11_CONSTEXPR U &operator*() & {
     return val();
   }
-  /// \group deref
   template <class U = T,
             detail::enable_if_t<!std::is_void<U>::value> * = nullptr>
   constexpr const U &&operator*() const && {
     return std::move(val());
   }
-  /// \group deref
   template <class U = T,
             detail::enable_if_t<!std::is_void<U>::value> * = nullptr>
   TL_EXPECTED_11_CONSTEXPR U &&operator*() && {
     return std::move(val());
   }
 
-  /// \returns whether or not the optional has a value
-  /// \group has_value
   constexpr bool has_value() const noexcept { return this->m_has_val; }
-  /// \group has_value
   constexpr explicit operator bool() const noexcept { return this->m_has_val; }
 
-  /// \returns the contained value if there is one, otherwise throws
-  /// [bad_expected_access]
-  ///
-  /// \group value
   template <class U = T,
             detail::enable_if_t<!std::is_void<U>::value> * = nullptr>
   TL_EXPECTED_11_CONSTEXPR const U &value() const & {
@@ -2034,7 +1896,6 @@ public:
       detail::throw_exception(bad_expected_access<E>(err().value()));
     return val();
   }
-  /// \group value
   template <class U = T,
             detail::enable_if_t<!std::is_void<U>::value> * = nullptr>
   TL_EXPECTED_11_CONSTEXPR U &value() & {
@@ -2042,7 +1903,6 @@ public:
       detail::throw_exception(bad_expected_access<E>(err().value()));
     return val();
   }
-  /// \group value
   template <class U = T,
             detail::enable_if_t<!std::is_void<U>::value> * = nullptr>
   TL_EXPECTED_11_CONSTEXPR const U &&value() const && {
@@ -2050,7 +1910,6 @@ public:
       detail::throw_exception(bad_expected_access<E>(err().value()));
     return std::move(val());
   }
-  /// \group value
   template <class U = T,
             detail::enable_if_t<!std::is_void<U>::value> * = nullptr>
   TL_EXPECTED_11_CONSTEXPR U &&value() && {
@@ -2059,26 +1918,17 @@ public:
     return std::move(val());
   }
 
-  /// \returns the unexpected value
-  /// \requires there is an unexpected value
-  /// \group error
   constexpr const E &error() const & { return err().value(); }
-  /// \group error
   TL_EXPECTED_11_CONSTEXPR E &error() & { return err().value(); }
-  /// \group error
   constexpr const E &&error() const && { return std::move(err().value()); }
-  /// \group error
   TL_EXPECTED_11_CONSTEXPR E &&error() && { return std::move(err().value()); }
 
-  /// \returns the stored value if there is one, otherwise returns `u`
-  /// \group value_or
   template <class U> constexpr T value_or(U &&v) const & {
     static_assert(std::is_copy_constructible<T>::value &&
                       std::is_convertible<U &&, T>::value,
                   "T must be copy-constructible and convertible to from U&&");
     return bool(*this) ? **this : static_cast<T>(std::forward<U>(v));
   }
-  /// \group value_or
   template <class U> TL_EXPECTED_11_CONSTEXPR T value_or(U &&v) && {
     static_assert(std::is_move_constructible<T>::value &&
                       std::is_convertible<U &&, T>::value,
@@ -2087,7 +1937,6 @@ public:
   }
 };
 
-/// \exclude
 namespace detail {
 template <class Exp> using exp_t = typename detail::decay_t<Exp>::value_type;
 template <class Exp> using err_t = typename detail::decay_t<Exp>::error_type;