[DOC] Added doxygen comments from spec (#1305)

* Added doxygen comments from spec * Removed tail spaces * Fixed clang (cherry picked from commit c4363f5)
uxlfoundation · Dec 8, 2020 · b5bfbdc · b5bfbdc
1 parent e15be9b
commit b5bfbdc
Show file tree

Hide file tree

Showing 17 changed files with 653 additions and 0 deletions.
diff --git a/.ci/pipeline/docs.yml b/.ci/pipeline/docs.yml
@@ -7,6 +7,7 @@ trigger:
   paths:
     include:
     - cpp/daal/include
+    - cpp/oneapi
     - docs
     - examples
 
@@ -19,6 +20,7 @@ pr:
   paths:
     include:
     - cpp/daal/include
+    - cpp/oneapi
     - docs
     - examples
 

diff --git a/cpp/oneapi/dal/algo/kmeans/common.hpp b/cpp/oneapi/dal/algo/kmeans/common.hpp
@@ -23,7 +23,11 @@ namespace oneapi::dal::kmeans {
 
 namespace task {
 namespace v1 {
+/// Tag-type that parameterizes entities used for solving
+/// :capterm:`clustering problem <clustering>`.
 struct clustering {};
+
+/// Alias tag-type for the clustering task.
 using by_default = clustering;
 } // namespace v1
 
@@ -34,7 +38,12 @@ using v1::by_default;
 
 namespace method {
 namespace v1 {
+/// Tag-type that denotes `Lloyd's <kmeans_t_math_lloyd_>`_ computational
+/// method.
 struct lloyd_dense {};
+
+/// Alias tag-type for `Lloyd's <kmeans_t_math_lloyd_>`_ computational
+/// method.
 using by_default = lloyd_dense;
 } // namespace v1
 
@@ -74,8 +83,19 @@ class descriptor_base : public base {
 
     descriptor_base();
 
+    /// The number of clusters k
+    /// @invariant :expr:`cluster_count > 0`
+    /// @remark default = 2
     std::int64_t get_cluster_count() const;
+
+    /// The maximum number of iterations :literal:`T`
+    /// @invariant :expr:`max_iteration_count >= 0`
+    /// @remark default = 100
     std::int64_t get_max_iteration_count() const;
+
+    /// The threshold $\\varepsilon$ for the stop condition
+    /// @invariant :expr:`accuracy_threshold >= 0.0`
+    /// @remark default = 0.0
     double get_accuracy_threshold() const;
 
 protected:
@@ -102,6 +122,13 @@ using v1::is_valid_task_v;
 
 namespace v1 {
 
+/// @tparam Float  The floating-point type that the algorithm uses for
+///                intermediate computations. Can be :expr:`float` or
+///                :expr:`double`.
+/// @tparam Method Tag-type that specifies an implementation of algorithm. Can
+///                be :expr:`method::lloyd`.
+/// @tparam Task   Tag-type that specifies the type of the problem to solve. Can
+///                be :expr:`task::clustering`.
 template <typename Float = detail::descriptor_base<>::float_t,
           typename Method = detail::descriptor_base<>::method_t,
           typename Task = detail::descriptor_base<>::task_t>
@@ -117,6 +144,7 @@ class descriptor : public detail::descriptor_base<Task> {
     using method_t = Method;
     using task_t = Task;
 
+    /// Creates a new instance of the class with the given :literal:`cluster_count`
     explicit descriptor(std::int64_t cluster_count = 2) {
         set_cluster_count(cluster_count);
     }
@@ -137,6 +165,8 @@ class descriptor : public detail::descriptor_base<Task> {
     }
 };
 
+/// @tparam Task Tag-type that specifies type of the problem to solve. Can
+///              be :expr:`task::clustering`.
 template <typename Task = task::by_default>
 class model : public base {
     static_assert(detail::is_valid_task_v<Task>);
@@ -145,15 +175,22 @@ class model : public base {
 public:
     using task_t = Task;
 
+    /// Creates a new instance of the class with the default property values.
     model();
 
+    /// A $k \\times p$ table with the cluster centroids. Each row of the
+    /// table stores one centroid.
+    /// @remark default = table{}
     const table& get_centroids() const;
 
     auto& set_centroids(const table& value) {
         set_centroids_impl(value);
         return *this;
     }
 
+    /// Number of clusters k in the trained model.
+    /// @invariant :expr:`cluster_count == centroids.row_count`
+    /// @remark default = 0
     std::int64_t get_cluster_count() const;
 
 protected:

diff --git a/cpp/oneapi/dal/algo/kmeans/infer_types.hpp b/cpp/oneapi/dal/algo/kmeans/infer_types.hpp
@@ -36,22 +36,31 @@ using v1::infer_result_impl;
 
 namespace v1 {
 
+/// @tparam Task Tag-type that specifies type of the problem to solve. Can
+///              be :expr:`task::clustering`.
 template <typename Task = task::by_default>
 class infer_input : public base {
     static_assert(detail::is_valid_task_v<Task>);
 
 public:
     using task_t = Task;
 
+    /// Creates a new instance of the class with the given :literal:`model` and
+    /// :literal:`data`
     infer_input(const model<Task>& trained_model, const table& data);
 
+    /// An $n \\times p$ table with the data to be assigned to the clusters,
+    /// where each row stores one feature vector.
+    /// @remark default = model<Task>{}
     const model<Task>& get_model() const;
 
     auto& set_model(const model<Task>& value) {
         set_model_impl(value);
         return *this;
     }
 
+    /// The trained K-Means model
+    /// @remark default = table{}
     const table& get_data() const;
 
     auto& set_data(const table& value) {
@@ -67,21 +76,31 @@ class infer_input : public base {
     dal::detail::pimpl<detail::infer_input_impl<Task>> impl_;
 };
 
+/// @tparam Task Tag-type that specifies type of the problem to solve. Can
+///              be :expr:`task::clustering`.
 template <typename Task = task::by_default>
 class infer_result {
     static_assert(detail::is_valid_task_v<Task>);
 
 public:
     using task_t = Task;
 
+    /// Creates a new instance of the class with the default property values.
     infer_result();
 
+    /// An $n \\times 1$ table with assignments labels to feature
+    /// vectors in the input data.
+    /// @remark default = table{}
     const table& get_labels() const;
     auto& set_labels(const table& value) {
         set_labels_impl(value);
         return *this;
     }
 
+    /// The value of the objective function $\\Phi_X(C)$, where C is
+    /// defined by the corresponding :expr:`infer_input::model::centroids`.
+    /// @invariant :expr:`objective_function_value >= 0.0`
+    /// @remark default = 0.0
     double get_objective_function_value() const;
 
     auto& set_objective_function_value(double value) {

diff --git a/cpp/oneapi/dal/algo/kmeans/train_types.hpp b/cpp/oneapi/dal/algo/kmeans/train_types.hpp
@@ -36,6 +36,8 @@ using v1::train_result_impl;
 
 namespace v1 {
 
+/// @tparam Task Tag-type that specifies type of the problem to solve. Can
+///              be :expr:`task::clustering`.
 template <typename Task = task::by_default>
 class train_input : public base {
     static_assert(detail::is_valid_task_v<Task>);
@@ -44,15 +46,22 @@ class train_input : public base {
     using task_t = Task;
 
     train_input(const table& data);
+
+    /// Creates a new instance of the class with the given :literal:`data` and
+    /// :literal:`initial_centroids`
     train_input(const table& data, const table& initial_centroids);
 
+    /// An $n \\times p$ table with the data to be clustered, where each row
+    /// stores one feature vector.
     const table& get_data() const;
 
     auto& set_data(const table& data) {
         set_data_impl(data);
         return *this;
     }
 
+    /// A $k \\times p$ table with the initial centroids, where each row
+    /// stores one centroid.
     const table& get_initial_centroids() const;
 
     auto& set_initial_centroids(const table& data) {
@@ -68,36 +77,50 @@ class train_input : public base {
     dal::detail::pimpl<detail::train_input_impl<Task>> impl_;
 };
 
+/// @tparam Task Tag-type that specifies type of the problem to solve. Can
+///              be :expr:`task::clustering`.
 template <typename Task = task::by_default>
 class train_result {
     static_assert(detail::is_valid_task_v<Task>);
 
 public:
     using task_t = Task;
 
+    /// Creates a new instance of the class with the default property values.
     train_result();
 
+    /// The trained K-means model
+    /// @remark default = model<Task>{}
     const model<Task>& get_model() const;
 
     auto& set_model(const model<Task>& value) {
         set_model_impl(value);
         return *this;
     }
 
+    /// An $n \\times 1$ table with the labels $y_i$ assigned to the
+    /// samples $x_i$ in the input data, $1 \\leq 1 \\leq n$.
+    /// @remark default = table{}
     const table& get_labels() const;
 
     auto& set_labels(const table& value) {
         set_labels_impl(value);
         return *this;
     }
 
+    /// The number of iterations performed by the algorithm.
+    /// @remark default = 0
+    /// @invariant :expr:`iteration_count >= 0`
     int64_t get_iteration_count() const;
 
     auto& set_iteration_count(std::int64_t value) {
         set_iteration_count_impl(value);
         return *this;
     }
 
+    /// The value of the objective function $\\Phi_X(C)$, where C is
+    /// :expr:`model.centroids` (see :expr:`kmeans::model::centroids`).
+    /// @invariant :expr:`objective_function_value >= 0.0`
     double get_objective_function_value() const;
 
     auto& set_objective_function_value(double value) {

diff --git a/cpp/oneapi/dal/algo/kmeans_init/common.hpp b/cpp/oneapi/dal/algo/kmeans_init/common.hpp
@@ -23,7 +23,10 @@ namespace oneapi::dal::kmeans_init {
 
 namespace task {
 namespace v1 {
+/// Tag-type that parameterizes entities used for obtaining the initial K-Means centroids.
 struct init {};
+
+/// Alias tag-type for the initialization task.
 using by_default = init;
 } // namespace v1
 
@@ -34,6 +37,8 @@ using v1::by_default;
 
 namespace method {
 namespace v1 {
+/// Tag-type that denotes `dense <kmeans_init_c_math_dense_>`_
+/// computational method.
 struct dense {};
 struct random_dense {};
 struct plus_plus_dense {};
@@ -81,6 +86,9 @@ class descriptor_base : public base {
 
     descriptor_base();
 
+    /// The number of clusters k
+    /// @invariant :expr:`cluster_count > 0`
+    /// @remark default = 2
     std::int64_t get_cluster_count() const;
 
 protected:
@@ -104,6 +112,13 @@ using v1::is_valid_task_v;
 
 namespace v1 {
 
+/// @tparam Float  The floating-point type that the algorithm uses for
+///                intermediate computations. Can be :expr:`float` or
+///                :expr:`double`.
+/// @tparam Method Tag-type that specifies an implementation
+///                of K-Means Initialization algorithm.
+/// @tparam Task   Tag-type that specifies the type of the problem to solve. Can
+///                be :expr:`task::init`.
 template <typename Float = detail::descriptor_base<>::float_t,
           typename Method = detail::descriptor_base<>::method_t,
           typename Task = detail::descriptor_base<>::task_t>
@@ -119,6 +134,7 @@ class descriptor : public detail::descriptor_base<Task> {
     using method_t = Method;
     using task_t = Task;
 
+    /// Creates a new instance of the class with the given :literal:`cluster_count`
     explicit descriptor(std::int64_t cluster_count = 2) {
         set_cluster_count(cluster_count);
     }

diff --git a/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp b/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp
@@ -36,15 +36,21 @@ using v1::compute_result_impl;
 
 namespace v1 {
 
+/// @tparam Task Tag-type that specifies type of the problem to solve. Can
+///              be :expr:`task::init`.
 template <typename Task = task::by_default>
 class compute_input : public base {
     static_assert(detail::is_valid_task_v<Task>);
 
 public:
     using task_t = Task;
 
+    /// Creates a new instance of the class with the given :literal:`data`.
     compute_input(const table& data);
 
+    /// An $n \\times p$ table with the data to be clustered, where each row
+    /// stores one feature vector.
+    /// @remark default = table{}
     const table& get_data() const;
 
     auto& set_data(const table& data) {
@@ -58,15 +64,21 @@ class compute_input : public base {
     dal::detail::pimpl<detail::compute_input_impl<Task>> impl_;
 };
 
+/// @tparam Task Tag-type that specifies type of the problem to solve. Can
+///              be :expr:`task::clustering`.
 template <typename Task = task::by_default>
 class compute_result {
     static_assert(detail::is_valid_task_v<Task>);
 
 public:
     using task_t = Task;
 
+    /// Creates a new instance of the class with the default property values.
     compute_result();
 
+    /// A $k \\times p$ table with the initial centroids. Each row of the
+    /// table stores one centroid.
+    /// @remark default = table{}
     const table& get_centroids() const;
 
     auto& set_centroids(const table& value) {