A few doc improvements for task api

shogun-toolbox · Aug 9, 2012 · 4286ace · 4286ace
1 parent 5e63792
commit 4286ace
Show file tree

Hide file tree

Showing 5 changed files with 135 additions and 35 deletions.
diff --git a/src/shogun/transfer/multitask/MultitaskLinearMachine.cpp b/src/shogun/transfer/multitask/MultitaskLinearMachine.cpp
@@ -190,7 +190,6 @@ SGVector<float64_t> CMultitaskLinearMachine::apply_get_outputs(CFeatures* data)
 SGVector<float64_t> CMultitaskLinearMachine::get_w() const
 {
 	SGVector<float64_t> w_(m_tasks_w.num_rows);
-	int32_t nnz = 0;
 	for (int32_t i=0; i<w_.vlen; i++)
 		w_[i] = m_tasks_w(i,m_current_task);
 	return w_;

diff --git a/src/shogun/transfer/multitask/Task.h b/src/shogun/transfer/multitask/Task.h
@@ -16,7 +16,11 @@
 namespace shogun
 {
 
-/** @brief used to represent tasks in multitask learning
+/** @brief class Task used to represent tasks in multitask learning.
+ * Essentially it represent a set of feature vector indices.
+ *
+ * @see CTaskGroup
+ * @see CTaskTree
  */
 class CTask : public CSGObject
 {
@@ -25,7 +29,7 @@ class CTask : public CSGObject
 	/** default constructor */
 	CTask();
 
-	/** constructor
+	/** constructor from range
 	 * @param min_index smallest index of the task
 	 * @param max_index largest index of the task
 	 * @param weight weight (optional)
@@ -34,7 +38,7 @@ class CTask : public CSGObject
 	CTask(index_t min_index, index_t max_index, 
 	      float64_t weight=1.0, const char* name="task");
 
-	/** constructor
+	/** constructor from indices
 	 * @param indices indices of the task
 	 * @param weight weight (optional)
 	 * @param name name of task (optional)
@@ -44,31 +48,71 @@ class CTask : public CSGObject
 	/** destructor */
 	virtual ~CTask();
 
-	/** is contiguous */
+	/** is contiguous 
+	 *
+	 * @return whether task is contiguous
+	 */
 	bool is_contiguous();
 
-	/** get indices */
+	/** get indices
+	 * 
+	 * @return indices 
+	 */
 	SGVector<index_t> get_indices() const { return m_indices; }
-	/** set indices */
+
+	/** set indices 
+	 *
+	 * @param indices task vector indices to set
+	 */
 	void set_indices(SGVector<index_t> indices) { m_indices = indices; }
 
-	/** get weight */
+	/** get weight of the task
+	 * 
+	 * @return weight of the task
+	 */
 	float64_t get_weight() const { return m_weight; }
-	/** set weight */
+
+	/** set weight of the task
+	 * 
+	 * @param weight weight of the task
+	 */
 	void set_weight(float64_t weight) { m_weight = weight; }
-	/** get task name */
+
+	/** get task name 
+	 * 
+	 * @return name of the task
+	 */
 	const char* get_task_name() const { return m_name; }
-	/** set task name */
+
+	/** set task name 
+	 *
+	 * @param name name of the task
+	 */
 	void set_task_name(const char* name) { m_name = name; }
 
-	/** add sub task */
+	/** add subtask 
+	 * should represent a subset of indices of the task
+	 *
+	 * @param sub_task subtask to add
+	 */
 	void add_subtask(CTask* sub_task);
-	/** get subtasks */
+
+	/** get all subtasks of the task
+	 *
+	 * @return subtasks of the task
+	 */
 	CList* get_subtasks();
-	/** get num subtasks */
+
+	/** get number of subtasks 
+	 *
+	 * @return number of subtasks
+	 */
 	int32_t get_num_subtasks();
 
-	/** get name */
+	/** get name 
+	 *
+	 * @return name of object
+	 */
 	virtual const char* get_name() const { return "Task"; };
 
 private:

diff --git a/src/shogun/transfer/multitask/TaskGroup.h b/src/shogun/transfer/multitask/TaskGroup.h
@@ -18,6 +18,11 @@
 namespace shogun
 {
 
+/** @brief class TaskGroup used to represent a group of tasks.
+ * Tasks in group do not overlap.
+ *
+ * @see CTask
+ */
 class CTaskGroup : public CTaskRelation
 {
 public:
@@ -28,33 +33,47 @@ class CTaskGroup : public CTaskRelation
 	/** destructor */
 	virtual ~CTaskGroup();
 
-	/** returns information about tasks
+	/** get tasks indices 
+	 *
+	 * @return array of vectors containing indices of each task
 	 */
 	virtual SGVector<index_t>* get_tasks_indices() const;
 
-	/** append task to the group */
+	/** append task to the group 
+	 *
+	 * @param task task to append
+	 */
 	void append_task(CTask* task);
 
-	/** get num tasks */
+	/** get number of tasks in the group
+	 *
+	 * @return number of tasks in the group
+	 */
 	virtual int32_t get_num_tasks() const;
 
-	/** get name */
+	/** get name 
+	 * 
+	 * @return name of the object
+	 */
 	const char* get_name() const { return "TaskGroup"; };
 
-	/** relation type */
+	/** get relation type 
+	 *
+	 * @return TASK_GROUP
+	 */
 	ETaskRelationType get_relation_type() const { return TASK_GROUP; }
 
 private:
 
+	/** init */
 	void init();
 
 protected:
 
-	/** tasks */
+	/** tasks of the task group */
 	CDynamicObjectArray* m_tasks;
 
 };
-
 }
 #endif
 
diff --git a/src/shogun/transfer/multitask/TaskRelation.h b/src/shogun/transfer/multitask/TaskRelation.h
@@ -9,17 +9,19 @@
 
 #ifndef TASKRELATION_H_
 #define TASKRELATION_H_
-
+#define IGNORE_IN_CLASSLIST
 #include <shogun/base/SGObject.h>
 
 namespace shogun
 {
 
-enum ETaskRelationType
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+IGNORE_IN_CLASSLIST enum ETaskRelationType
 {
 	TASK_TREE,
 	TASK_GROUP
 };
+#endif
 
 /** @brief used to represent tasks in multitask learning
  */
@@ -37,16 +39,28 @@ class CTaskRelation : public CSGObject
 	{
 	}
 
-	/** get name */
+	/** get name
+	 *
+	 * @return name of the object
+	 */
 	virtual const char* get_name() const { return "TaskRelation"; };
 
-	/** get relation type */
+	/** get relation type (not implemented)
+	 *
+	 * @return type of relation
+	 */
 	virtual ETaskRelationType get_relation_type() const = 0;
 
-	/** get tasks indices */
+	/** get tasks indices (not implemented)
+	 *
+	 * @return array of vectors containing indices of each task
+	 */
 	virtual SGVector<index_t>* get_tasks_indices() const = 0;
 
-	/** get num tasks */
+	/** get number of tasks in the group (not implemented)
+	 *
+	 * @return number of tasks in the group
+	 */
 	virtual int32_t get_num_tasks() const = 0;
 };
 

diff --git a/src/shogun/transfer/multitask/TaskTree.h b/src/shogun/transfer/multitask/TaskTree.h
@@ -16,6 +16,12 @@
 namespace shogun
 {
 
+/** @brief class TaskTree used to represent a tree of tasks.
+ * Tree is constructed via task with subtasks (and subtasks of subtasks ..)
+ * passed to the TaskTree.
+ *
+ * @see CTask
+ */
 class CTaskTree : public CTaskRelation
 {
 public:
@@ -34,28 +40,46 @@ class CTaskTree : public CTaskRelation
 	/** get tasks indices */
 	virtual SGVector<index_t>* get_tasks_indices() const;
 
-	/** get num tasks */
+	/** get number of leaf tasks in the tree
+	 *
+	 * @return number of leaf tasks in the tree
+	 */
 	virtual int32_t get_num_tasks() const;
 
-	/** returns information about blocks relations
+	/** returns information about task
 	 * in SLEP "ind_t" format
+	 *
+	 * @return SLEP ind_t of the tree
 	 */
 	SGVector<float64_t> get_SLEP_ind_t();
 
-	/** get root task */
+	/** get root task 
+	 *
+	 * @return root task of the tree 
+	 */
 	CTask* get_root_task() const { SG_REF(m_root_task); return m_root_task; }
-	/** set root task */
+
+	/** set root task 
+	 *
+	 * @param root_task task to set as root of the tree
+	 */
 	void set_root_task(CTask* root_task) { SG_REF(root_task); SG_UNREF(m_root_task); m_root_task = root_task; }
 
-	/** get name */
+	/** get name 
+	 *
+	 * @return name of the object
+	 */
 	const char* get_name() const { return "TaskTree"; };
 
-	/** get relation type */
+	/** get relation type 
+	 *
+	 * @return TASK_TREE
+	 */
 	ETaskRelationType get_relation_type() const { return TASK_TREE; }
 
 protected:
 
-	/** root task */
+	/** root task of the tree */
 	CTask* m_root_task;
 
 };