[Xenomai-help] Re: RT_TASK_INFO status

[Nathaniel Villaume <villaume@domain.hid>]

[-- Attachment #1: Type: text/plain, Size: 2312 bytes --]

Jan,
Ok, so I played around with your request some.

 My goal here is to produce documentation, but not at the expense of 
source-code readability and maintainability.  It's not hard to document 
defines, but it CAN make the source look uglier.
Witness nucleus/thread.h:

/*! @def XNSUSP */
#define XNSUSP 0x00000001 /*!< @brief Suspended */

/*! @define XNSUSP */
#define XNSUSP 0x00000002 /*!< Sleep-wait for a resource. */

In the first case, @brief is used to get the comment up into the brief 
listing (duh). If this is not done, then a detailed section is created 
with the comment, which is a little kludgier on the output end, but 
still completely usable.

Second order of business: refering to this new documentation. In 
include/native/task.h I made a group native_task_status that encompasses 
all the define documentation. This makes it easy to refer to from within 
the RT_TASK_INFO::status documentation (and anywhere else)

Third: I removed the duplication as you requested. This is not without 
consequence.  Please note the difference between RT_TASK_INFO and 
RT_TASK_MCB (which remainded the same).  To keep the brief member 
documentation, I had to use the /**  comment */ syntax. This is 
inconsistent with other usage, but... this gives the results we want.

Please see the patch and let me know what you think for this initial set.
Again, the decisions to be made are:
1.) Do we document the defines at all?
1a) If so, do we include brief in the define documentation (or not)?
1b) Do we group the defines (or not) for easy reference? (they show up 
under modules/native/Task Status)

My default action is to continue with the style/grouping as in the patch.

-Nate

Jan Kiszka wrote:

>Nathaniel Villaume wrote:
>  
>
>>In RT_TASK_INFO, can someone tell me what is the set of all possible
>>values for status?
>>I'd like to include that in the documentation.
>>    
>>
>
>They are defined in include/native/task.h [1], but they widely redirect
>to defines in include/nucleus/thread.h [2]. Maybe you could add comments
>to the native/task.h defines and include them in doxygen.
>
>Thanks again for your effort!
>Jan
>
>[1]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/native/task.h#L37
>[2]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/nucleus/thread.h#L25
>
>  
>

[-- Attachment #2: task_defines.diff --]
[-- Type: text/plain, Size: 3624 bytes --]

Index: include/native/task.h
===================================================================
--- include/native/task.h	(revision 1383)
+++ include/native/task.h	(working copy)
@@ -34,8 +34,20 @@
 #define T_CPU(cpu) (1 << (24 + (cpu & 7))) /* Up to 8 cpus [0-7] */
 #define T_CPUMASK  0xff000000
 
-/* Status/mode flags. */
-#define T_BLOCKED  XNPEND
+/*! 
+  \ingroup native
+  @defgroup native_task_status Task Status 
+  @brief Defines used to specify task state and/or mode 
+  */
+/*! @addtogroup native_task_status 
+  @{
+  */
+
+/*! @def T_BLOCKED  
+  Task is blocked. See define #XNPEND*/
+#define T_BLOCKED  XNPEND 
+/*! @def T_DELAYED  
+  Task is delayed. See define #XNDELAY*/
 #define T_DELAYED  XNDELAY
 #define T_READY    XNREADY
 #define T_DORMANT  XNDORMANT
@@ -49,6 +61,7 @@
 #define T_RPIOFF   XNRPIOFF
 #define T_PRIMARY  0x00000200	/* Recycle internal bits status which */
 #define T_JOINABLE 0x00000400	/* won't be passed to the nucleus.  */
+/*! @} */ /* Ends addtogroup native_task_status */
 
 /* Task hook types. */
 #define T_HOOK_START  XNHOOK_THREAD_START
@@ -68,31 +81,50 @@
 struct rt_queue_msg;
 struct rt_task;
 
+/*! @brief Structure containing task-information useful to users.
+ *
+ *  @see rt_task_inquire()
+  */
 typedef struct rt_task_info {
+    
+    /** Base priority. */
+    int bprio;  
 
-    int bprio;			/* !< Base priority. */
+    /** Current priority. Can change through Priority Inheritance.*/
+    int cprio;
+    
+    /** Task's status.
+     * Status may be any of the defines in task.h
+     *  @see native_task_status shows possible values.
+     */
+    unsigned status; 
+    
+    /** Time of next release.*/
+    RTIME relpoint; 
+    
+    /** Symbolic name assigned in creation */
+    char name[XNOBJECT_NAME_LEN];  
 
-    int cprio;			/* !< Current priority. */
-
-    unsigned status;		/* !< Status. */
-
-    RTIME relpoint;		/* !< Next periodic release point. */
-
-    char name[XNOBJECT_NAME_LEN]; /* !< Symbolic name. */
-
 } RT_TASK_INFO;
 
 #define RT_MCB_FSTORE_LIMIT  64
+/*! @typedef RT_TASK_MCB
+  @brief Structure used in passing messages between tasks.
 
+  @param  flowid  Flow identifier.
+  @param  opcode  Operation code.
+  @param  data    Message address.
+  @param  size    Message size (bytes).
+*/
 typedef struct rt_task_mcb {
 
-    int flowid;			/* !< Flow identifier. */
+    int flowid;
 
-    int opcode;			/* !< Operation code. */
+    int opcode;
 
-    caddr_t data;		/* !< Address of message. */
+    caddr_t data;
 
-    size_t size;		/* !< Size of message. */
+    size_t size;
 
 } RT_TASK_MCB;
 
Index: include/nucleus/thread.h
===================================================================
--- include/nucleus/thread.h	(revision 1383)
+++ include/nucleus/thread.h	(working copy)
@@ -1,4 +1,4 @@
-/*
+/*! @file nucleus/thread.h
  * Copyright (C) 2001,2002,2003 Philippe Gerum <rpm@xenomai.org>.
  *
  * Xenomai is free software; you can redistribute it and/or modify
@@ -23,9 +23,13 @@
 #include <nucleus/timer.h>
 
 /* Status flags */
-#define XNSUSP    0x00000001	/* Suspended */
-#define XNPEND    0x00000002	/* Sleep-wait for a resource */
-#define XNDELAY   0x00000004	/* Delayed */
+
+/*! @def XNSUSP */
+#define XNSUSP    0x00000001	/*!< @brief Suspended */
+/*! @def XNPEND */
+#define XNPEND    0x00000002	/*!< Sleep-wait for a resource */
+/*! @def XNPEND */
+#define XNDELAY   0x00000004	/*!< Delayed */
 #define XNREADY   0x00000008	/* Linked to the ready queue */
 #define XNDORMANT 0x00000010	/* Not started yet or killed */
 #define XNZOMBIE  0x00000020	/* Zombie thread in deletion process */