mtapi_cpp: amended documentation

mtapi_cpp/include/embb/mtapi/action.h

@@ -50,11 +50,23 @@ class Action {
     handle_.tag = 0;
   }
 
-  Action(Action const & other) : handle_(other.handle_) {
+  /**
+   * Copy constructs an Action.
+   */
+  Action(
+    Action const & other               /**< The Action to copy. */
+    ) : handle_(other.handle_) {
     // empty
   }
 
-  Action & operator=(Action const & other) {
+  /**
+   * Copies an Action.
+   *
+   * \returns Reference to this object.
+   */
+  Action & operator=(
+    Action const & other               /**< The Action to copy. */
+    ) {
     handle_ = other.handle_;
     return *this;
   }

mtapi_cpp/include/embb/mtapi/group.h

@@ -51,11 +51,23 @@ namespace mtapi {
  */
 class Group {
  public:
-  Group(Group const & other) : handle_(other.handle_) {
+  /**
+   * Copy constructs a Group.
+   */
+  Group(
+    Group const & other                /**< The Group to copy. */
+    ) : handle_(other.handle_) {
     // empty
   }
 
-  Group & operator=(Group const & other) {
+  /**
+   * Copies a Group.
+   *
+   * \returns Reference to this object.
+   */
+  Group & operator=(
+    Group const & other                /**< The Group to copy. */
+    ) {
     handle_ = other.handle_;
     return *this;
   }

mtapi_cpp/include/embb/mtapi/node.h

@@ -68,6 +68,9 @@ namespace mtapi {
  */
 class Node {
  public:
+  /**
+   * Function type for simple SMP Tasks.
+   */
   typedef embb::base::Function<void, TaskContext &> SMPFunction;
 
   /**
@@ -285,16 +288,37 @@ class Node {
       MTAPI_DEFAULT_TASK_ATTRIBUTES);
   }
 
-  Job GetJob(mtapi_job_id_t job_id) {
+  /**
+   * Retrieves a handle to the Job identified by \c job_id within the domain
+   * of the local Node.
+   *
+   * \returns The handle to the requested Job.
+   * \waitfree
+   */
+  Job GetJob(
+    mtapi_job_id_t job_id              /**< [in] The id of the job */
+    ) {
     return Job(job_id, domain_id_);
   }
 
-  Job GetJob(mtapi_job_id_t job_id, mtapi_domain_t domain_id) {
+  /**
+   * Retrieves a handle to the Job identified by \c job_id and \c domain_id.
+   *
+   * \returns The handle to the requested Job.
+   * \waitfree
+   */
+  Job GetJob(
+    mtapi_job_id_t job_id,             /**< [in] The id of the job */
+    mtapi_domain_t domain_id           /**< [in] The domain id to use */
+    ) {
     return Job(job_id, domain_id);
   }
 
   /**
    * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \threadsafe
    */
   Action CreateAction(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -303,7 +327,7 @@ class Node {
                                        Tasks using this Action */
     mtapi_size_t node_local_data_size, /**< Size of node local data */
     ActionAttributes const & attributes
-    /**< Attributes of the Action */
+                                       /**< Attributes of the Action */
     ) {
     return Action(job_id, func, node_local_data, node_local_data_size,
       &attributes.GetInternal());
@@ -311,6 +335,9 @@ class Node {
 
   /**
    * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \threadsafe
    */
   Action CreateAction(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -325,18 +352,24 @@ class Node {
 
   /**
    * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \threadsafe
    */
   Action CreateAction(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
     mtapi_action_function_t func,      /**< The action function */
     ActionAttributes const & attributes
-    /**< Attributes of the Action */
+                                       /**< Attributes of the Action */
     ) {
     return Action(job_id, func, MTAPI_NULL, 0, &attributes.GetInternal());
   }
 
   /**
    * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \threadsafe
    */
   Action CreateAction(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -347,6 +380,9 @@ class Node {
 
   /**
    * Constructs a Group object with default attributes.
+   *
+   * \returns The handle to the new Group.
+   * \threadsafe
    */
   Group CreateGroup() {
     return Group(MTAPI_GROUP_ID_NONE, MTAPI_DEFAULT_GROUP_ATTRIBUTES);
@@ -354,6 +390,9 @@ class Node {
 
   /**
    * Constructs a Group object with default attributes and the given ID.
+   *
+   * \returns The handle to the new Group.
+   * \threadsafe
    */
   Group CreateGroup(
     mtapi_group_id_t id                /**< A user defined ID of the Group. */
@@ -363,14 +402,21 @@ class Node {
 
   /**
    * Constructs a Group object using the given Attributes.
+   *
+   * \returns The handle to the new Group.
+   * \threadsafe
    */
   Group CreateGroup(
-    GroupAttributes const & group_attr) {
+    GroupAttributes const & group_attr /**< The GroupAttributes to use. */
+    ) {
     return Group(MTAPI_GROUP_ID_NONE, &group_attr.GetInternal());
   }
 
   /**
    * Constructs a Group object with given attributes and ID.
+   *
+   * \returns The handle to the new Group.
+   * \threadsafe
    */
   Group CreateGroup(
     mtapi_group_id_t id,               /**< A user defined ID of the Group. */
@@ -381,6 +427,9 @@ class Node {
 
   /**
    * Constructs a Queue with the given Job and default attributes.
+   *
+   * \returns The handle to the new Queue.
+   * \threadsafe
    */
   Queue CreateQueue(
     Job & job                          /**< The Job to use for the Queue. */
@@ -390,6 +439,9 @@ class Node {
 
   /**
    * Constructs a Queue with the given Job and QueueAttributes.
+   *
+   * \returns The handle to the new Queue.
+   * \threadsafe
    */
   Queue CreateQueue(
     Job const & job,                   /**< The Job to use for the Queue. */

mtapi_cpp/include/embb/mtapi/queue.h

@@ -51,11 +51,23 @@ namespace mtapi {
  */
 class Queue {
  public:
-  Queue(Queue const & other) : handle_(other.handle_) {
+  /**
+   * Copy constructs a Queue.
+   */
+  Queue(
+    Queue const & other                /**< The Queue to copy. */
+    ) : handle_(other.handle_) {
     // empty
   }
 
-  Queue & operator=(Queue const & other) {
+  /**
+   * Copies a Queue.
+   *
+   * \returns Reference to this object.
+   */
+  Queue & operator=(
+    Queue const & other                /**< The Queue to copy. */
+    ) {
     handle_ = other.handle_;
     return *this;
   }

mtapi_cpp/include/embb/mtapi/task_attributes.h

@@ -103,8 +103,15 @@ class TaskAttributes {
     return *this;
   }
 
+  /**
+   * Sets the ExecutionPolicy of a Task.
+   * The ExecutionPolicy determines the affinity and priority of a Task.
+   *
+   * \returns Reference to this object.
+   * \notthreadsafe
+   */
   TaskAttributes & SetPolicy(
-    ExecutionPolicy const & policy
+    ExecutionPolicy const & policy     /**< The ExecutionPolicy to set. */
     ) {
     SetPriority(policy.GetPriority());
     SetAffinity(policy.GetAffinity());