Merge branch 'embb609_doxygen_warnings' into development

mtapi_cpp/include/embb/mtapi/action.h

@@ -44,23 +44,42 @@ class Action {
   /**
   /**
    * Constructs an Action.
    * Constructs an Action.
    * The Action object will be invalid.
    * The Action object will be invalid.
+   *
+   * \waitfree
    */
    */
   Action() {
   Action() {
     handle_.id = 0;
     handle_.id = 0;
     handle_.tag = 0;
     handle_.tag = 0;
   }
   }
 
 
-  Action(Action const & other) : handle_(other.handle_) {
+  /**
+   * Copies an Action.
+   *
+   * \waitfree
+   */
+  Action(
+    Action const & other               /**< Action to copy */
+    ) : handle_(other.handle_) {
     // empty
     // empty
   }
   }
 
 
-  Action & operator=(Action const & other) {
+  /**
+   * Copies an Action.
+   *
+   * \returns Reference to this object.
+   * \waitfree
+   */
+  Action & operator=(
+    Action const & other               /**< Action to copy */
+    ) {
     handle_ = other.handle_;
     handle_ = other.handle_;
     return *this;
     return *this;
   }
   }
 
 
   /**
   /**
    * Deletes an Action.
    * Deletes an Action.
+   *
+   * \threadsafe
    */
    */
   void Delete() {
   void Delete() {
     mtapi_action_delete(handle_, MTAPI_INFINITE, MTAPI_NULL);
     mtapi_action_delete(handle_, MTAPI_INFINITE, MTAPI_NULL);
@@ -82,6 +101,8 @@ class Action {
  private:
  private:
   /**
   /**
    * Constructs an Action.
    * Constructs an Action.
+   *
+   * \threadsafe
    */
    */
   Action(
   Action(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */

mtapi_cpp/include/embb/mtapi/group.h

@@ -51,17 +51,34 @@ namespace mtapi {
  */
  */
 class Group {
 class Group {
  public:
  public:
-  Group(Group const & other) : handle_(other.handle_) {
+  /**
+   * Copies a Group.
+   *
+   * \waitfree
+   */
+  Group(
+    Group const & other                /**< Group to copy */
+    ) : handle_(other.handle_) {
     // empty
     // empty
   }
   }
 
 
-  Group & operator=(Group const & other) {
+  /**
+   * Copies a Group.
+   *
+   * \returns Reference to this object.
+   * \waitfree
+   */
+  Group & operator=(
+    Group const & other                /**< Group to copy */
+    ) {
     handle_ = other.handle_;
     handle_ = other.handle_;
     return *this;
     return *this;
   }
   }
 
 
   /**
   /**
    * Deletes a Group object.
    * Deletes a Group object.
+   *
+   * \threadsafe
    */
    */
   void Delete() {
   void Delete() {
     // delete the group, ignore status
     // delete the group, ignore status
@@ -245,6 +262,8 @@ class Group {
   /**
   /**
    * Constructs a Group object with given attributes and ID.
    * Constructs a Group object with given attributes and ID.
    * Requires an initialized Node.
    * Requires an initialized Node.
+   *
+   * \threadsafe
    */
    */
   Group(
   Group(
     mtapi_group_id_t id,               /**< A user defined ID of the Group. */
     mtapi_group_id_t id,               /**< A user defined ID of the Group. */
@@ -256,14 +275,21 @@ class Group {
     internal::CheckStatus(status);
     internal::CheckStatus(status);
   }
   }
 
 
+  /**
+   * Starts a new Task in this Group.
+   *
+   * \returns The handle to the started Task.
+   * \threadsafe
+   */
   Task Start(
   Task Start(
-    mtapi_task_id_t task_id,
-    mtapi_job_hndl_t job,
-    const void * arguments,
-    mtapi_size_t arguments_size,
-    void * results,
-    mtapi_size_t results_size,
+    mtapi_task_id_t task_id,           /**< A user defined ID of the Task. */
+    mtapi_job_hndl_t job,              /**< The Job to execute. */
+    const void * arguments,            /**< Pointer to the arguments. */
+    mtapi_size_t arguments_size,       /**< Size of the argument buffer. */
+    void * results,                    /**< Pointer to the results. */
+    mtapi_size_t results_size,         /**< Size of the result buffer. */
     mtapi_task_attributes_t const * attributes
     mtapi_task_attributes_t const * attributes
+                                       /**< Attributes of the Task */
     ) {
     ) {
     mtapi_status_t status;
     mtapi_status_t status;
     mtapi_task_hndl_t task_hndl =
     mtapi_task_hndl_t task_hndl =

mtapi_cpp/include/embb/mtapi/node.h

@@ -68,6 +68,9 @@ namespace mtapi {
  */
  */
 class Node {
 class Node {
  public:
  public:
+  /**
+   * Function type for simple SMP interface.
+   */
   typedef embb::base::Function<void, TaskContext &> SMPFunction;
   typedef embb::base::Function<void, TaskContext &> SMPFunction;
 
 
   /**
   /**
@@ -285,16 +288,37 @@ class Node {
       MTAPI_DEFAULT_TASK_ATTRIBUTES);
       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_);
     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);
     return Job(job_id, domain_id);
   }
   }
 
 
   /**
   /**
    * Constructs an Action.
    * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \lockfree
    */
    */
   Action CreateAction(
   Action CreateAction(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -311,6 +335,9 @@ class Node {
 
 
   /**
   /**
    * Constructs an Action.
    * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \lockfree
    */
    */
   Action CreateAction(
   Action CreateAction(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -325,6 +352,9 @@ class Node {
 
 
   /**
   /**
    * Constructs an Action.
    * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \lockfree
    */
    */
   Action CreateAction(
   Action CreateAction(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -337,6 +367,9 @@ class Node {
 
 
   /**
   /**
    * Constructs an Action.
    * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \lockfree
    */
    */
   Action CreateAction(
   Action CreateAction(
     mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
     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.
    * Constructs a Group object with default attributes.
+   *
+   * \returns The handle to the new Group.
+   * \lockfree
    */
    */
   Group CreateGroup() {
   Group CreateGroup() {
     return Group(MTAPI_GROUP_ID_NONE, MTAPI_DEFAULT_GROUP_ATTRIBUTES);
     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.
    * Constructs a Group object with default attributes and the given ID.
+   *
+   * \returns The handle to the new Group.
+   * \lockfree
    */
    */
   Group CreateGroup(
   Group CreateGroup(
     mtapi_group_id_t id                /**< A user defined ID of the Group. */
     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.
    * Constructs a Group object using the given Attributes.
+   *
+   * \returns The handle to the new Group.
+   * \lockfree
    */
    */
   Group CreateGroup(
   Group CreateGroup(
-    GroupAttributes const & group_attr) {
+    GroupAttributes const & group_attr /**< The GroupAttributes to use. */
+    ) {
     return Group(MTAPI_GROUP_ID_NONE, &group_attr.GetInternal());
     return Group(MTAPI_GROUP_ID_NONE, &group_attr.GetInternal());
   }
   }
 
 
   /**
   /**
    * Constructs a Group object with given attributes and ID.
    * Constructs a Group object with given attributes and ID.
+   *
+   * \returns The handle to the new Group.
+   * \lockfree
    */
    */
   Group CreateGroup(
   Group CreateGroup(
     mtapi_group_id_t id,               /**< A user defined ID of the Group. */
     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.
    * Constructs a Queue with the given Job and default attributes.
+   *
+   * \returns The handle to the new Queue.
+   * \lockfree
    */
    */
   Queue CreateQueue(
   Queue CreateQueue(
     Job & job                          /**< The Job to use for the Queue. */
     Job & job                          /**< The Job to use for the Queue. */
@@ -390,6 +439,9 @@ class Node {
 
 
   /**
   /**
    * Constructs a Queue with the given Job and QueueAttributes.
    * Constructs a Queue with the given Job and QueueAttributes.
+   *
+   * \returns The handle to the new Queue.
+   * \lockfree
    */
    */
   Queue CreateQueue(
   Queue CreateQueue(
     Job const & job,                   /**< The Job to use for the Queue. */
     Job const & job,                   /**< The Job to use for the Queue. */

mtapi_cpp/include/embb/mtapi/queue.h

@@ -51,17 +51,34 @@ namespace mtapi {
  */
  */
 class Queue {
 class Queue {
  public:
  public:
-  Queue(Queue const & other) : handle_(other.handle_) {
+  /**
+   * Copies a Queue.
+   *
+   * \waitfree
+   */
+  Queue(
+    Queue const & other                /**< The Queue to copy */
+    ) : handle_(other.handle_) {
     // empty
     // empty
   }
   }
 
 
-  Queue & operator=(Queue const & other) {
+  /**
+   * Copies a Queue.
+   *
+   * \returns Reference to this object.
+   * \waitfree
+   */
+  Queue & operator=(
+    Queue const & other                /**< The Queue to copy */
+    ) {
     handle_ = other.handle_;
     handle_ = other.handle_;
     return *this;
     return *this;
   }
   }
 
 
   /**
   /**
    * Deletes a Queue object.
    * Deletes a Queue object.
+   *
+   * \threadsafe
    */
    */
   void Delete() {
   void Delete() {
     mtapi_queue_delete(handle_, MTAPI_INFINITE, MTAPI_NULL);
     mtapi_queue_delete(handle_, MTAPI_INFINITE, MTAPI_NULL);

mtapi_cpp/include/embb/mtapi/task_attributes.h

@@ -103,8 +103,15 @@ class TaskAttributes {
     return *this;
     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(
   TaskAttributes & SetPolicy(
-    ExecutionPolicy const & policy
+    ExecutionPolicy const & policy     /**< The ExecutionPolicy to set. */
     ) {
     ) {
     SetPriority(policy.GetPriority());
     SetPriority(policy.GetPriority());
     SetAffinity(policy.GetAffinity());
     SetAffinity(policy.GetAffinity());