Merge and migrate doc test for core module

include/eve/module/core/regular/abs.hpp

@@ -48,9 +48,9 @@ struct abs_t : elementwise_callable<abs_t, Options, saturated_option>
 //!
 //!   **Parameters**
 //!
-//!     * `x` :  [SIMD or scalar arithmetic value](@ref eve::value).
+//!     * `x` :  [SIMD or scalar value](@ref eve::value).
 //!
-//!    **Return value**
+//!   **Return value**
 //!
 //!    The [elementwise](@ref glossary_elementwise) absolute value of `x`, if it is representable.
 //!    More specifically, for signed integers : the absolute value of eve::valmin is not representable and
@@ -63,7 +63,7 @@ struct abs_t : elementwise_callable<abs_t, Options, saturated_option>
 //!
 //!   @groupheader{Example}
 //!
-//!   @godbolt{doc/core/regular/abs.cpp}
+//!   @godbolt{doc/core/abs.cpp}
 //!
 //!   @groupheader{Semantic Modifiers}
 //!
@@ -72,17 +72,12 @@ struct abs_t : elementwise_callable<abs_t, Options, saturated_option>
 //!     The call `eve::abs[mask](x)` provides a masked version of `eve::abs` which is
 //!     equivalent to `if_else (mask, abs(x), x)`.
 //!
-//!     **Example**
-//!     @godbolt{doc/core/masked/abs.cpp}
-//!
 //!   * eve::saturated
 //!
 //!     The call `eve::abs[eve::saturated](x)` computes a saturated version of eve::abs.
 //!     More specifically, for any signed integer value `x`, the expression
 //!     `eve::abs[eve::saturated](eve::valmin(as(x)))` evaluates to `eve::valmax(as(x))`.
 //!
-//!     **Example**
-//!     @godbolt{doc/core/saturated/abs.cpp}
 //! @}
 //======================================================================================================================
 inline constexpr auto abs = functor<abs_t>;

include/eve/module/core/regular/absmax.hpp

@@ -61,16 +61,15 @@ namespace eve
 //!
 //!    **Return value**
 //!
-//!    The absolute value of the maximal element
-//!    is returned.
+//!    The absolute value of the maximal element is returned.
 //!
 //!    @note
 //!     If any element of the inputs is a NaN,
 //!     the corresponding output element is system-dependent.
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/absmax.cpp}
+//!  @godbolt{doc/core/absmax.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -79,15 +78,14 @@ namespace eve
 //!     The call `eve::absmax[mask](x, ...)` provides a masked version of `eve::absmax` which is
 //!     equivalent to `eve::if_else (mask, absmax(x, ...), x)`
 //!
-//!      **Example**
+//!   * eve::pedantic, eve::numeric, eve::saturated
 //!
-//!        @godbolt{doc/core/masked/absmax.cpp}
-//!
-//!   * eve::pedantic,  eve::numeric
-//!
-//!     The call `d(eve::absmax)(...)`, where d is one of these two decorators, is equivalent to
+//!     The call `eve::absmax[d](...)`, where d is one of these two first decorators, is equivalent to
 //!     `eve::abs (d( eve::max )(...))`.
 //!
+//!     The call `eve::absmax[d][saturated](...)`, where d is one of these two first decorators or is not present, is equivalent to
+//!     `eve::abs[saturated](d( eve::max )(...))`.
+//!
 //! @}
 //================================================================================================
 inline constexpr auto absmax = functor<absmax_t>;

include/eve/module/core/regular/absmin.hpp

@@ -69,7 +69,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/absmin.cpp}
+//!  @godbolt{doc/core/absmin.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -78,15 +78,14 @@ namespace eve
 //!     The call `eve::absmin[mask](x, ...)` provides a masked version of `eve::absmin` which is
 //!     equivalent to `eve::if_else (mask, absmin(x, ...), x)`
 //!
-//!      **Example**
+//!   * eve::pedantic,  eve::numeric, eve::saturated
 //!
-//!        @godbolt{doc/core/masked/absmin.cpp}
-//!
-//!   * eve::pedantic,  eve::numeric
-//!
-//!     The call `d(eve::absmin)(...)`, where d is one of these two decorators, is equivalent to
+//!     The call `eve::absmin[d](...)`, where d is one of these two first decorators, is equivalent to
 //!     `eve::abs (d( eve::min )(...))`.
 //!
+//!     The call `eve::absmin[d][saturated](...)`, where d is one of these two first decorators or is not present, is equivalent to
+//!     `eve::abs[saturated](d( eve::min )(...))`.
+//!
 //! @}
 //================================================================================================
 inline constexpr auto absmin = functor<absmin_t>;

include/eve/module/core/regular/add.hpp

@@ -52,32 +52,23 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/add.cpp}
+//!  @godbolt{doc/core/add.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
 //!   * Masked Call
 //!
 //!     The call `eve::add[mask](x, ...)` provides a masked
-//!     version of `add` which is
-//!     equivalent to `if_else(mask, eve::add(x, ...), x)`
-//!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/masked/add.cpp}
+//!     version of `add` which is equivalent to `if_else(mask, eve::add(x, ...), x)`
 //!
 //!   * eve::saturated
 //!
 //!     The call `eve::saturated(eve::add)(...)` computes
 //!     a saturated version of `eve::add`.
 //!
-//!     Take care that for signed integral
-//!     entries this kind of addition is not associative at all.
+//!     Take care that for signed integral entries this kind of addition is not associative at all.
 //!     This call perform saturated additions in reverse incoming order.
 //!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/saturated/add.cpp}
 //! @}
 //================================================================================================
 EVE_MAKE_CALLABLE(add_, add);

include/eve/module/core/regular/agm.hpp

@@ -70,7 +70,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/agm.cpp}
+//!  @godbolt{doc/core/agm.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -79,9 +79,6 @@ namespace eve
 //!     The call `eve::agm[mask](x, ...)` provides a masked version of `agm` which is
 //!     equivalent to `if_else(mask, agm(x, ...), x)`
 //!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/masked/agm.cpp}
 //! @}
 //================================================================================================
   inline constexpr auto agm = functor<agm_t>;

include/eve/module/core/regular/all.hpp

@@ -49,7 +49,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/all.cpp}
+//!  @godbolt{doc/core/all.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -59,10 +59,6 @@ namespace eve
 //!     version of `all` which is
 //!     equivalent to : all not masked elements are not zero.
 //!
-//!      **Example**
-//!
-//! @godbolt{doc/core/masked/all.cpp}
-//!
 //!  @}
 //================================================================================================
 EVE_MAKE_CALLABLE(all_, all);

include/eve/module/core/regular/any.hpp

@@ -52,7 +52,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/any.cpp}
+//!  @godbolt{doc/core/any.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -62,10 +62,6 @@ namespace eve
 //!     version of `any` which is
 //!     equivalent to : any not masked elements is not zero.
 //!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/masked/any.cpp}
-//!
 //! @}
 //================================================================================================
 EVE_MAKE_CALLABLE(any_, any);

include/eve/module/core/regular/average.hpp

@@ -82,7 +82,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/average.cpp}
+//!  @godbolt{doc/core/average.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -92,19 +92,16 @@ namespace eve
 //!     version of `average` which is
 //!     equivalent to `if_else(mask, average(x, ...), x)`
 //!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/masked/average.cpp}
-//!
 //!   * eve::raw
 //!
 //!     when `raw(average)(x, args, ...)` is used, no provision is made to avoid
 //!     overflows for more than 2 parameters.
 //!
-//!      **Example**
+//!   * eve::downward,  eve::upward
 //!
-//!        @godbolt{doc/core/raw/average.cpp}
-//! @}
+//!     only for two integral values, see above
+//!    
+//!//! @}
 //================================================================================================
   inline constexpr auto average = functor<average_t>;
 

include/eve/module/core/regular/binarize.hpp

@@ -51,7 +51,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/binarize.cpp}
+//!  @godbolt{doc/core/binarize.cpp}
 //! @}
 //================================================================================================
 

include/eve/module/core/regular/binarize_not.hpp

@@ -51,7 +51,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/binarize_not.cpp}
+//!  @godbolt{doc/core/binarize_not.cpp}
 //! @}
 //================================================================================================
 

include/eve/module/core/regular/bit_and.hpp

@@ -56,7 +56,7 @@ namespace eve
 //!   namespace eve
 //!   {
 //!      template< eve::value T, eve::value Ts... >
-//!      T bit_and(T x, Ts... xs) noexcept;
+//!      bit_value<T, Ts...> bit_and(T x, Ts... xs) noexcept;
 //!   }
 //!   @endcode
 //!
@@ -67,8 +67,8 @@ namespace eve
 //!
 //!    **Return value**
 //!
-//!      The value of the bitwise AND of its arguments in the type of the first one
-//!      is returned.
+//!      The value of the bitwise AND of its arguments converted to the bit_value<T,  Ts...>
+//!      type is returned.
 //!
 //!    @note
 //!
@@ -78,7 +78,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/bit_and.cpp}
+//!  @godbolt{doc/core/bit_and.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -88,9 +88,6 @@ namespace eve
 //!     version of `bit_and` which is
 //!     equivalent to `if_else(mask, bit_and(x, ...), x)`
 //!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/masked/bit_and.cpp}
 //! @}
 //================================================================================================
   inline constexpr auto bit_and = functor<bit_and_t>;

include/eve/module/core/regular/bit_andnot.hpp

@@ -50,7 +50,7 @@ namespace eve
 //!   namespace eve
 //!   {
 //!      template< eve::value T, eve::value Ts... >
-//!      T bit_andnot(T x, Ts... xs) noexcept;
+//!      bit_value<T, Ts...> bit_andnot(T x, Ts... xs) noexcept;
 //!   }
 //!   @endcode
 //!
@@ -61,14 +61,16 @@ namespace eve
 //!
 //!    **Return value**
 //!
-//!     * For two parameters it computes the  bitwise ANDNOT of the two parameters
-//!     * For more than two parameters the call is  semantically equivalent to to `bit_andnot(a0,
-//!     bit_and(xs...))`
-//!     *  The value returned is in the type of the first parameter
+//!     * The return value type is bit_value<T,  Ts...> Each parameter is converted
+//!       to this type and then:  
+//!
+//!       * For two parameters it computes the  bitwise ANDNOT of the two parameters
+//!       * For more than two parameters the call is  semantically equivalent to to `bit_andnot(a0,
+//!         bit_and(xs...))`
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/bit_andnot.cpp}
+//!  @godbolt{doc/core/bit_andnot.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -78,9 +80,6 @@ namespace eve
 //!     version of `bit_andnot` which is
 //!     equivalent to `if_else(mask, bit_andnot(x, ...), x)`
 //!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/masked/bit_andnot.cpp}
 //! @}
 //================================================================================================
   inline constexpr auto bit_andnot = functor<bit_andnot_t>;

include/eve/module/core/regular/bit_cast.hpp

@@ -57,7 +57,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/bit_cast.cpp}
+//!  @godbolt{doc/core/bit_cast.cpp}
 //!
 //! @}
 //================================================================================================

include/eve/module/core/regular/bit_ceil.hpp

@@ -66,7 +66,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/bit_ceil.cpp}
+//!  @godbolt{doc/core/bit_ceil.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -76,9 +76,6 @@ namespace eve
 //!     version of `bit_ceil` which is
 //!     equivalent to `if_else(mask, bit_ceil(x, ...), x)`
 //!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/masked/bit_ceil.cpp}
 //! @}
 //================================================================================================
   inline constexpr auto bit_ceil = functor<bit_ceil_t>;

include/eve/module/core/regular/bit_flip.hpp

@@ -44,7 +44,7 @@ namespace eve
 //!   @code
 //!   namespace eve
 //!   {
-//!      template< eunsigned_value T, integral_value I>
+//!      template<unsigned_value T, integral_value I>
 //!      T bit_flip(T x, I i) noexcept;
 //!   }
 //!   @endcode
@@ -61,7 +61,7 @@ namespace eve
 //!
 //!  @groupheader{Example}
 //!
-//!  @godbolt{doc/core/regular/bit_flip.cpp}
+//!  @godbolt{doc/core/bit_flip.cpp}
 //!
 //!  @groupheader{Semantic Modifiers}
 //!
@@ -71,10 +71,6 @@ namespace eve
 //!     version of `bit_flip` which is
 //!     equivalent to `if_else(mask, bit_flip(x, ...), x)`
 //!
-//!      **Example**
-//!
-//!        @godbolt{doc/core/masked/bit_flip.cpp}
-//!
 //! @}
 //================================================================================================
   inline constexpr auto bit_flip = functor<bit_flip_t>;