From 6a074363a2657a86b5f1ea0fc1185f68ad9f3c08 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 16 Jan 2006 15:13:58 +0000 Subject: 2006-01-16 Joel Sherrill Large patch to improve Doxygen output. As a side-effect, grammar and spelling errors were corrected, spacing errors were address, and some variable names were improved. * libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS. * score/Doxyfile: Set output directory. Predefine some macro values. Turn on graphical output. * score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/object.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/macros/README, score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, score/src/threadstartmultitasking.c: Improve generated Doxygen output. Fix spelling and grammar errors in comments. Correct names of some variables and propagate changes. --- cpukit/score/inline/rtems/score/chain.inl | 218 ++++++++++++++++++++++-------- 1 file changed, 161 insertions(+), 57 deletions(-) (limited to 'cpukit/score/inline/rtems/score/chain.inl') diff --git a/cpukit/score/inline/rtems/score/chain.inl b/cpukit/score/inline/rtems/score/chain.inl index 3a6f10e2e6..d394ec93e1 100644 --- a/cpukit/score/inline/rtems/score/chain.inl +++ b/cpukit/score/inline/rtems/score/chain.inl @@ -10,7 +10,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -28,9 +28,16 @@ * @{ */ -/** - * This function returns TRUE if \a left and \a right are equal, +/** @brief Are Two Nodes Equal + * + * This function returns TRUE if @a left and @a right are equal, * and FALSE otherwise. + * + * @param[in] left is the node on the left hand side of the comparison. + * @param[in] right is the node on the left hand side of the comparison. + * + * @return This function returns TRUE if @a left and @a right are equal, + * and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal( Chain_Node *left, @@ -40,28 +47,43 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal( return left == right; } -/** +/** @brief Is this Chain Control Pointer Null + * * This function returns TRUE if the_chain is NULL and FALSE otherwise. + * + * @param[in] the_chain is the chain to be checked for empty status. + * + * @return This method returns TRUE if the_chain is NULL and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_null( Chain_Control *the_chain ) { - return ( the_chain == NULL ); + return (the_chain == NULL); } -/** + +/** @brief Is the Chain Node Pointer NULL + * * This function returns TRUE if the_node is NULL and FALSE otherwise. + * + * @param[in] the_node is the node pointer to check. + * + * @return This method returns TRUE if the_node is NULL and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Chain_Is_null_node( Chain_Node *the_node ) { - return ( the_node == NULL ); + return (the_node == NULL); } -/** +/** @brief Return pointer to Chain Head + * * This function returns a pointer to the first node on the chain. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This method returns the permanent head node of the chain. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head( Chain_Control *the_chain @@ -70,8 +92,13 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head( return (Chain_Node *) the_chain; } -/** +/** @brief Return pointer to Chain Tail + * * This function returns a pointer to the last node on the chain. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This method returns the permanent tail node of the chain. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail( Chain_Control *the_chain @@ -80,92 +107,132 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail( return (Chain_Node *) &the_chain->permanent_null; } -/** - * This function returns TRUE if there a no nodes on the_chain and +/** @brief Is the Chain Empty + * + * This function returns TRUE if there a no nodes on @a the_chain and + * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This function returns TRUE if there a no nodes on @a the_chain and * FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_empty( Chain_Control *the_chain ) { - return ( the_chain->first == _Chain_Tail( the_chain ) ); + return (the_chain->first == _Chain_Tail(the_chain)); } -/** +/** @brief Is this the First Node on the Chain + * * This function returns TRUE if the_node is the first node on a chain and * FALSE otherwise. + * + * @param[in] the_node is the node the caller wants to know if it is + * the first node on a chain. + * + * @return This function returns TRUE if @a the_node is the first node on + * a chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_first( Chain_Node *the_node ) { - return ( the_node->previous == NULL ); + return (the_node->previous == NULL); } -/** - * This function returns TRUE if \a the_node is the last node on a chain and +/** @brief Is this the Last Node on the Chain + * + * This function returns TRUE if @a the_node is the last node on a chain and * FALSE otherwise. + * + * @param[in] the_node is the node to check as the last node. + * + * @return This function returns TRUE if @a the_node is the last node on + * a chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_last( Chain_Node *the_node ) { - return ( the_node->next == NULL ); + return (the_node->next == NULL); } -/** - * This function returns TRUE if there is only one node on \a the_chain and +/** @brief Does this Chain have only One Node + * + * This function returns TRUE if there is only one node on @a the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This function returns TRUE if there is only one node on + * @a the_chain and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Chain_Has_only_one_node( Chain_Control *the_chain ) { - return ( the_chain->first == the_chain->last ); + return (the_chain->first == the_chain->last); } -/** - * This function returns TRUE if the_node is the head of the_chain and +/** @brief Is this Node the Chain Head + * + * This function returns TRUE if @a the_node is the head of the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to check for being the Chain Head. + * + * @return This function returns TRUE if @a the_node is the head of + * @a the_chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_head( Chain_Control *the_chain, Chain_Node *the_node ) { - return ( the_node == _Chain_Head( the_chain ) ); + return (the_node == _Chain_Head(the_chain)); } -/** +/** @brief Is this Node the Chail Tail + * * This function returns TRUE if the_node is the tail of the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to check for being the Chain Tail. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_tail( Chain_Control *the_chain, Chain_Node *the_node ) { - return ( the_node == _Chain_Tail( the_chain ) ); + return (the_node == _Chain_Tail(the_chain)); } -/** +/** @brief Initialize this Chain as Empty + * * This routine initializes the specified chain to contain zero nodes. + * + * @param[in] the_chain is the chain to be initialized. */ - RTEMS_INLINE_ROUTINE void _Chain_Initialize_empty( Chain_Control *the_chain ) { - the_chain->first = _Chain_Tail( the_chain ); + the_chain->first = _Chain_Tail(the_chain); the_chain->permanent_null = NULL; - the_chain->last = _Chain_Head( the_chain ); + the_chain->last = _Chain_Head(the_chain); } -/** +/** @brief Extract this Node (unprotected) + * * This routine extracts the_node from the chain on which it resides. - * It does NOT disable interrupts to insure the atomicity of the + * It does NOT disable interrupts to ensure the atomicity of the * extract operation. + * + * @param[in] the_node is the node to be extracted. */ RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected( Chain_Node *the_node @@ -180,10 +247,19 @@ RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected( previous->next = next; } -/** +/** @brief Get the First Node (unprotected) + * * This function removes the first node from the_chain and returns - * a pointer to that node. It does NOT disable interrupts to insure + * a pointer to that node. It does NOT disable interrupts to ensure * the atomicity of the get operation. + * + * @param[in] the_chain is the chain to attempt to get the first node from. + * + * @return This method returns the first node on the chain even if it is + * the Chain Tail. + * + * @note This routine assumes that there is at least one node on the chain + * and always returns a node even if it is the Chain Tail. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected( Chain_Control *the_chain @@ -195,33 +271,46 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected( return_node = the_chain->first; new_first = return_node->next; the_chain->first = new_first; - new_first->previous = _Chain_Head( the_chain ); + new_first->previous = _Chain_Head(the_chain); return return_node; } -/** +/** @brief Get the First Node (unprotected) + * * This function removes the first node from the_chain and returns * a pointer to that node. If the_chain is empty, then NULL is returned. - * It does NOT disable interrupts to insure the atomicity of the - * get operation. + * + * @param[in] the_chain is the chain to attempt to get the first node from. + * + * @return This method returns the first node on the chain or NULL if the + * chain is empty. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * get operation. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_unprotected( Chain_Control *the_chain ) { - if ( !_Chain_Is_empty( the_chain ) ) - return _Chain_Get_first_unprotected( the_chain ); + if ( !_Chain_Is_empty(the_chain)) + return _Chain_Get_first_unprotected(the_chain); else return NULL; } -/** +/** @brief Insert a Node (unprotected) + * * This routine inserts the_node on a chain immediately following - * after_node. It does NOT disable interrupts to insure the atomicity - * of the extract operation. + * after_node. + * + * @param[in] after_node is the node which will precede @a the_node on the + * chain. + * @param[in] the_node is the node to be inserted. + * + * @note It does NOT disable interrupts to ensure the atomicity + * of the extract operation. */ - RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected( Chain_Node *after_node, Chain_Node *the_node @@ -236,10 +325,15 @@ RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected( before_node->previous = the_node; } -/** +/** @brief Append a Node (unprotected) + * * This routine appends the_node onto the end of the_chain. - * It does NOT disable interrupts to insure the atomicity of the - * append operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be appended. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * append operation. */ RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected( Chain_Control *the_chain, @@ -248,37 +342,47 @@ RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected( { Chain_Node *old_last_node; - the_node->next = _Chain_Tail( the_chain ); + the_node->next = _Chain_Tail(the_chain); old_last_node = the_chain->last; the_chain->last = the_node; old_last_node->next = the_node; the_node->previous = old_last_node; } -/** +/** @brief Prepend a Node (unprotected) + * * This routine prepends the_node onto the front of the_chain. - * It does NOT disable interrupts to insure the atomicity of the - * prepend operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be prepended. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * prepend operation. */ RTEMS_INLINE_ROUTINE void _Chain_Prepend_unprotected( Chain_Control *the_chain, Chain_Node *the_node ) { - _Chain_Insert_unprotected( _Chain_Head( the_chain ), the_node ); + _Chain_Insert_unprotected(_Chain_Head(the_chain), the_node); } -/** +/** @brief Prepend a Node (protected) + * * This routine prepends the_node onto the front of the_chain. - * It disables interrupts to insure the atomicity of the - * prepend operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be prepended. + * + * @note It disables interrupts to ensure the atomicity of the + * prepend operation. */ RTEMS_INLINE_ROUTINE void _Chain_Prepend( Chain_Control *the_chain, Chain_Node *the_node ) { - _Chain_Insert( _Chain_Head( the_chain ), the_node ); + _Chain_Insert(_Chain_Head(the_chain), the_node); } /**@}*/ -- cgit v1.2.3