corrected documentation comments r1-r5

modules/r2/pcb.c

@@ -6,14 +6,14 @@
  * @version R3
  *
  */
+#ifndef DOXYGEN
 #include "pcb.h"
 #include <string.h>
 #include "../mpx_supt.h"
 #include "../r3/context.h"
-
+#endif
 
 /**
- * @name ready_queue
  * PCBs stored in priority order with highest priority at head 
  */
 static struct pcb_queue ready_queue;
@@ -23,6 +23,8 @@ static struct pcb_queue ready_queue;
  */
 static struct pcb_queue blocked_queue;
 
+#ifndef DOXYGEN
+
 static char *enum_process_state[] = {"running", "ready", "blocked"};
 static char *enum_process_suspended[] = {"suspended", "unsuspended"};
 static char *enum_process_class[] = {"application", "system"};
@@ -47,8 +49,12 @@ enum process_suspended
   false /**< PCB process is not suspended. */
 } __attribute__ ((packed));
 
+#endif
+
 /**
 * Struct that will describe PCB Processes.
+* These members are private to prevent potential manipulation so that 
+* the MPX system can remain functioning correctly.
 */
 struct pcb_struct
 {
@@ -65,6 +71,8 @@ struct pcb_struct
 
 /**
 * Queue structure that will store PCBs.
+* These members are private to prevent potential manipulation so that 
+* the MPX system can remain functioning correctly.
 */
 struct pcb_queue
 {
@@ -73,6 +81,9 @@ struct pcb_queue
   struct pcb_struct * tail; /**< Pointer to the end/tail of the queue. */
 };
 
+#ifndef DOXYGEN
+
+
 /**
  * @name  pcb_init
  * @brief Initiates the PCB queues
@@ -733,3 +744,4 @@ void shutdown_pcb()
     free_pcb(temp);
   }
 }
+#endif

modules/r2/pcb.h

@@ -13,13 +13,13 @@
 #include "../errno.h"
 
 
-/* @brief The defualt size of the stack for the PCB */
+/** The defualt size of the stack for the PCB. */
 #define SIZE_OF_STACK 1024
-/* @brief The max length of the PCB name string */
+/** The max length of the PCB name string. */
 #define SIZE_OF_PCB_NAME 10
-
+/** The name of the command handler PCB. */
 #define COMMHAND_PCB_NAME "commhand"
-
+/** The name of the idle PCB. */
 #define IDLE_PCB_NAME "idle"
 
 /**
@@ -31,14 +31,28 @@ enum process_class
   pcb_class_sys /**< Process is a system process. */
 } __attribute__ ((packed));
 
+/**
+ * @brief The PCB structure.
+ * PCB members are private to prevent potential manipulation so that 
+ * the MPX system can remain functioning correctly.
+ */
 struct pcb_struct;
+
+/**
+ * @brief The PCB queue structure.
+ * The PCB queue structure members are private to prevent potential manipulation so that 
+ * the MPX system can remain functioning correctly.
+ */
 struct pcb_queue;
+
+/**
+ * The context structure. Please refer to @ref context.h for more information.
+ */
 struct context;
 
 /**
  * @name  pcb_init
- * @brief Initiates the PCB queues
- *
+ * @brief Initializes the PCB queues
  */
 void pcb_init();
 
@@ -56,7 +70,7 @@ struct pcb_struct * allocate_pcb();
  *
  * @param   pcb_ptr The pointer to the PCB
  *
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_INVPARA   The PCB probably had not been removed from queue before free it.
@@ -73,7 +87,8 @@ error_t free_pcb(struct pcb_struct * pcb_ptr);
  * @param   pClass      Process class (system or application).
  * @param   pPriority   Process priority (0 ~ 9).
  *
- * @return  NULL if error occured, otherwise, the pointer that point to the PCB structure.
+ * @return  The pointer that point to the PCB structure.
+ * @return  NULL if error occured.
  */
 struct pcb_struct * setup_pcb(const char * pName, const enum process_class pClass, const unsigned char pPriority);
 
@@ -83,7 +98,8 @@ struct pcb_struct * setup_pcb(const char * pName, const enum process_class pClas
  *
  * @param   pName  The char pointer to the desired searched name
  *
- * @return PCB pointer if found, NULL if PCB is not found
+ * @return The PCB pointer.
+ * @return NULL if PCB is not found
  */
 struct pcb_struct * find_pcb(const char * pName);
 
@@ -93,7 +109,7 @@ struct pcb_struct * find_pcb(const char * pName);
  *
  * @param   pcb_ptr The pointer to the PCB
  *
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -107,7 +123,7 @@ error_t insert_pcb(struct pcb_struct * pcb_ptr);
  *
  * @param   pcb_ptr The pointer to the PCB
  *
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -121,7 +137,7 @@ error_t remove_pcb(struct pcb_struct * pcb_ptr);
  *
  * @param   pcb_ptr The pointer to the PCB
  *
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -134,7 +150,7 @@ error_t suspend_pcb(struct pcb_struct * pcb_ptr);
  *
  * @param   pcb_ptr The pointer to the PCB
  *
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -147,7 +163,7 @@ error_t resume_pcb(struct pcb_struct * pcb_ptr);
  *
  * @param   pcb_ptr 	The PCB pointer.
  * @param   pPriorty  The assigned priorirty
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -161,7 +177,7 @@ error_t set_pcb_priority(struct pcb_struct * pcb_ptr, const unsigned char pPrior
  * @brief Displays the name, class, state, suspend status, and priority of a PCB.
  *
  * @param   pName 	The PCB pointer.
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -171,24 +187,18 @@ error_t show_pcb(struct pcb_struct * pcb_ptr);
 /**
  * @name show_all_processes
  * @brief Displays all of the processes and their attributes.
- *
- * @return   VOID.
  */
 void show_all_processes();
 
 /**
  * @name show_ready_processes
  * @brief Displays all of the ready processes and their attributes.
- *
- * @return  VOID.
  */
 void show_ready_processes();
 
 /**
  * @name show_blocked_processes
- * @brief displays all blocked processes and their attributes
- *
- * @return  VOID.
+ * @brief Displays all blocked processes and their attributes
  */
 void show_blocked_processes();
 
@@ -198,7 +208,7 @@ void show_blocked_processes();
  *
  * @param   pcb_ptr The pointer to the PCB
  *
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -212,7 +222,7 @@ error_t block_pcb(struct pcb_struct * pcb_ptr);
  *
  * @param   pcb_ptr The pointer to the PCB
  *
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -224,8 +234,6 @@ error_t unblock_pcb(struct pcb_struct * pcb_ptr);
  * @name get_running_process
  * @brief gets a unsuspended and unblocked process from the front of the queue, and sets it to running state.
  *
- * @param   None
- *
  * @return NULL if there is no process available, otherwise, the pointer that point to the PCB structure.
  */
 struct pcb_struct * get_running_process();
@@ -237,7 +245,7 @@ struct pcb_struct * get_running_process();
  * @param   pcb_ptr The pointer to the PCB.
  * @param   new_stack_top The pointer to the new stack top.
  *
- * @return The error code.
+ * @return The appropiate error code. See @ref errno.h for details.
  *    Possible error code to be returned:
  *      E_NOERROR   No error.
  *      E_NULL_PTR  Null pointer error.
@@ -251,7 +259,8 @@ error_t save_running_process(struct pcb_struct * pcb_ptr, struct context * new_s
  *
  * @param   pcb_ptr The pointer to the PCB.
  *
- * @return NULL if the pcb_ptr is NULL, otherwise, the pointer that point to the stack top of the specific PCB.
+ * @return The pointer that point to the stack top of the specific PCB.
+ * @return NULL if the pcb_ptr is NULL.
  */
 unsigned char * get_stack_top(struct pcb_struct * pcb_ptr);
 
@@ -261,15 +270,14 @@ unsigned char * get_stack_top(struct pcb_struct * pcb_ptr);
  *
  * @param   pcb_ptr The pointer to the PCB.
  *
- * @return NULL if the pcb_ptr is NULL, otherwise, the pointer that point to the stack base of the specific PCB.
+ * @return The pointer that point to the stack base of the specific PCB.
+ * @return NULL if the pcb_ptr is NULL.
  */
 unsigned char * get_stack_base(struct pcb_struct * pcb_ptr);
 
 /**
  * @name shutdown_pcb
  * @brief called when system is going to shutdown, removes all PCBs, free all PCBs.
- * 
- * @return VOID
  */
 void shutdown_pcb();