Fix docs builds (#2562)

This PR fixes two errors in docs builds:
1. a function with `void` return type had a `@return` parameter, which
causes an error. The error was `error: found documented return type for
raft::random::device::warp_random_sample that does not return anything`
2. a function with return type `std::vector<S>` was being misinterpreted
as the beginning of an HTML tag `<S>`. This resulted in `error: end of
comment block while expecting command </s>`.

Author: bdice

cpp/include/raft/random/device/sample.cuh

@@ -27,12 +27,14 @@ namespace raft::random::device {
 
 /**
  * @brief warp-level random sampling of an index.
+ *
  * It selects an index with the given discrete probability
- * distribution(represented by weights of each index)
+ * distribution(represented by weights of each index).
+ * Only thread 0 will contain the valid reduced result.
+ *
  * @param rng random number generator, must have next_u32() function
  * @param weight weight of the rank/index.
  * @param idx index to be used as rank
- * @return only the thread0 will contain valid reduced result
  */
 template <typename T, typename rng_t, typename i_t = int>
 DI void warp_random_sample(rng_t& rng, T& weight, i_t& idx)

cpp/include/raft/util/itertools.hpp

@@ -36,7 +36,7 @@ namespace raft::util::itertools {
  *              fields of the structure (if the structure has more fields, some might be initialized
  *              with their default value).
  * @param lists One or more initializer lists.
- * @return std::vector<S> A vector of structures containing the cartesian product.
+ * @return `std::vector<S>` A vector of structures containing the cartesian product.
  */
 template <typename S, typename... Args>
 std::vector<S> product(std::initializer_list<Args>... lists)