diff --git a/modules/libcom/src/as/asTrapWrite.h b/modules/libcom/src/as/asTrapWrite.h index 7bce659cb..8f93fa1ee 100644 --- a/modules/libcom/src/as/asTrapWrite.h +++ b/modules/libcom/src/as/asTrapWrite.h @@ -8,9 +8,9 @@ \*************************************************************************/ /** - * @file asTrapWrite.h - * @brief API for monitoring external put operations to an IOC. - * @author Marty Kraimer + * \file asTrapWrite.h + * \brief API for monitoring external put operations to an IOC. + * \author Marty Kraimer * * The access security subsystem provides an API asTrapWrite that makes * put/write requests visible to any facility that registers a listener. @@ -26,40 +26,43 @@ extern "C" { #endif /** - * @brief The message passed to registered listeners. + * \brief The message passed to registered listeners. */ typedef struct asTrapWriteMessage { - const char *userid; /**< @brief Userid of whoever orginated the request. */ - const char *hostid; /**< @brief Hostid of whoever orginated the request. */ - void *serverSpecific; /**< @brief A field for use by the server. - * - * Any listener that uses this field must know what type of - * server is forwarding the put requests. This pointer holds - * the value the server provides to asTrapWriteWithData(), which - * for RSRV is the dbChannel pointer for the target field. - */ - void *userPvt; /**< @brief A field for use by the @ref asTrapWriteListener. - * - * When the listener is called before the write, this has the - * value 0. The listener can give it any value it desires - * and it will have the same value when the listener gets - * called again after the write. */ - int dbrType; /**< @brief Data type from ca/db_access.h, NOT dbFldTypes.h */ - int no_elements; /**< @brief Array length */ - void *data; /**< @brief Might be NULL if no data is available */ + const char *userid; /**< \brief Userid of whoever orginated the request. */ + const char *hostid; /**< \brief Hostid of whoever orginated the request. */ + /** \brief A field for use by the server. + * + * Any listener that uses this field must know what type of + * server is forwarding the put requests. This pointer holds + * the value the server provides to asTrapWriteWithData(), which + * for RSRV is the dbChannel pointer for the target field. + */ + void *serverSpecific; + /** \brief A field for use by the \ref asTrapWriteListener. + * + * When the listener is called before the write, this has the + * value 0. The listener can give it any value it desires + * and it will have the same value when the listener gets + * called again after the write. + */ + void *userPvt; + int dbrType; /**< \brief Data type from ca/db_access.h, NOT dbFldTypes.h */ + int no_elements; /**< \brief Array length */ + void *data; /**< \brief Might be NULL if no data is available */ } asTrapWriteMessage; /** - * @brief An identifier needed to unregister an listener. + * \brief An identifier needed to unregister an listener. */ typedef void *asTrapWriteId; /** - * @brief Pointer to a listener function. + * \brief Pointer to a listener function. * * Each registered listener function is called twice for every put; once * before and once after the write is performed. - * The listener may set @c userPvt in the first call and retrieve it in the + * The listener may set \c userPvt in the first call and retrieve it in the * second call. * * Each asTrapWriteMessage can change or may be deleted after the user's @@ -71,15 +74,15 @@ typedef void *asTrapWriteId; typedef void(*asTrapWriteListener)(asTrapWriteMessage *pmessage,int after); /** - * @brief Register function to be called on asTrapWriteListener. - * @param func The listener function to be called. - * @return A listener identifier for unregistering this listener. + * \brief Register function to be called on asTrapWriteListener. + * \param func The listener function to be called. + * \return A listener identifier for unregistering this listener. */ epicsShareFunc asTrapWriteId epicsShareAPI asTrapWriteRegisterListener( asTrapWriteListener func); /** - * @brief Unregister asTrapWriteListener. - * @param id Listener identifier from asTrapWriteRegisterListener(). + * \brief Unregister asTrapWriteListener. + * \param id Listener identifier from asTrapWriteRegisterListener(). */ epicsShareFunc void epicsShareAPI asTrapWriteUnregisterListener( asTrapWriteId id); diff --git a/modules/libcom/src/bucketLib/bucketLib.h b/modules/libcom/src/bucketLib/bucketLib.h index a461cfd8a..0336d6e18 100644 --- a/modules/libcom/src/bucketLib/bucketLib.h +++ b/modules/libcom/src/bucketLib/bucketLib.h @@ -7,16 +7,16 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file bucketLib.h - * @author Jeffrey O. Hill - * @brief A hash table. Do not use for new code. + * \file bucketLib.h + * \author Jeffrey O. Hill + * \brief A hash table. Do not use for new code. * - * @details + * \details * A hash table for which keys may be unsigned integers, pointers, or * strings. This API is used by the IOC's Channel Access Server, but * it should not be used by other code. * - * @note Storage for identifiers must persist until an item is deleted + * \note Storage for identifiers must persist until an item is deleted */ #ifndef INCbucketLibh @@ -30,13 +30,13 @@ extern "C" { #include "epicsTypes.h" #include "shareLib.h" -/** @brief Internal: bucket identifier */ +/** \brief Internal: bucket identifier */ typedef unsigned BUCKETID; -/** @brief Internal: bucket key type */ +/** \brief Internal: bucket key type */ typedef enum {bidtUnsigned, bidtPointer, bidtString} buckTypeOfId; -/** @brief Internal: bucket item structure */ +/** \brief Internal: bucket item structure */ typedef struct item{ struct item *pItem; const void *pId; @@ -44,7 +44,7 @@ typedef struct item{ buckTypeOfId type; }ITEM; -/** @brief Internal: Hash table structure */ +/** \brief Internal: Hash table structure */ typedef struct bucket{ ITEM **pTable; void *freeListPVT; @@ -53,140 +53,140 @@ typedef struct bucket{ unsigned nInUse; }BUCKET; /** - * @brief Creates a new hash table - * @param nHashTableEntries Table size - * @return Pointer to the newly created hash table, or NULL. + * \brief Creates a new hash table + * \param nHashTableEntries Table size + * \return Pointer to the newly created hash table, or NULL. */ epicsShareFunc BUCKET * epicsShareAPI bucketCreate (unsigned nHashTableEntries); /** - * @brief Release memory used by a hash table - * @param *prb Pointer to the hash table - * @return S_bucket_success - * @note All items must be deleted from the hash table before calling this. + * \brief Release memory used by a hash table + * \param *prb Pointer to the hash table + * \return S_bucket_success + * \note All items must be deleted from the hash table before calling this. */ epicsShareFunc int epicsShareAPI bucketFree (BUCKET *prb); /** - * @brief Display information about a hash table - * @param *prb Pointer to the hash table - * @return S_bucket_success + * \brief Display information about a hash table + * \param *prb Pointer to the hash table + * \return S_bucket_success */ epicsShareFunc int epicsShareAPI bucketShow (BUCKET *prb); /** - * @brief Add an item identified by an unsigned int to the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @param *pApp Pointer to the payload - * @return Status value + * \brief Add an item identified by an unsigned int to the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \param *pApp Pointer to the payload + * \return Status value */ epicsShareFunc int epicsShareAPI bucketAddItemUnsignedId (BUCKET *prb, const unsigned *pId, const void *pApp); /** - * @brief Add an item identified by a pointer to the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @param *pApp Pointer to the payload - * @return Status value + * \brief Add an item identified by a pointer to the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \param *pApp Pointer to the payload + * \return Status value */ epicsShareFunc int epicsShareAPI bucketAddItemPointerId (BUCKET *prb, void * const *pId, const void *pApp); /** - * @brief Add an item identified by a string to the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @param *pApp Pointer to the payload - * @return Status value + * \brief Add an item identified by a string to the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \param *pApp Pointer to the payload + * \return Status value */ epicsShareFunc int epicsShareAPI bucketAddItemStringId (BUCKET *prb, const char *pId, const void *pApp); /** - * @brief Remove an item identified by a string from the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Status value + * \brief Remove an item identified by a string from the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Status value */ epicsShareFunc int epicsShareAPI bucketRemoveItemUnsignedId (BUCKET *prb, const unsigned *pId); /** - * @brief Remove an item identified by a pointer from the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Status value + * \brief Remove an item identified by a pointer from the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Status value */ epicsShareFunc int epicsShareAPI bucketRemoveItemPointerId (BUCKET *prb, void * const *pId); /** - * @brief Remove an item identified by a string from the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Status value + * \brief Remove an item identified by a string from the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Status value */ epicsShareFunc int epicsShareAPI bucketRemoveItemStringId (BUCKET *prb, const char *pId); /** - * @brief Find an item identified by an unsigned int in the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Item's payload pointer, or NULL if not found + * \brief Find an item identified by an unsigned int in the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Item's payload pointer, or NULL if not found */ epicsShareFunc void * epicsShareAPI bucketLookupItemUnsignedId (BUCKET *prb, const unsigned *pId); /** - * @brief Find an item identified by a pointer in the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Item's payload pointer, or NULL if not found + * \brief Find an item identified by a pointer in the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Item's payload pointer, or NULL if not found */ epicsShareFunc void * epicsShareAPI bucketLookupItemPointerId (BUCKET *prb, void * const *pId); /** - * @brief Find an item identified by a string in the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Item's payload pointer, or NULL if not found + * \brief Find an item identified by a string in the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Item's payload pointer, or NULL if not found */ epicsShareFunc void * epicsShareAPI bucketLookupItemStringId (BUCKET *prb, const char *pId); /** - * @brief Find and delete an item identified by an unsigned int from the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Item's payload pointer, or NULL if not found + * \brief Find and delete an item identified by an unsigned int from the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Item's payload pointer, or NULL if not found */ epicsShareFunc void * epicsShareAPI bucketLookupAndRemoveItemUnsignedId (BUCKET *prb, const unsigned *pId); /** - * @brief Find and delete an item identified by a pointer from the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Item's payload pointer, or NULL if not found + * \brief Find and delete an item identified by a pointer from the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Item's payload pointer, or NULL if not found */ epicsShareFunc void * epicsShareAPI bucketLookupAndRemoveItemPointerId (BUCKET *prb, void * const *pId); /** - * @brief Find and delete an item identified by a string from the table - * @param *prb Pointer to the hash table - * @param *pId Pointer to the identifier - * @return Item's payload pointer, or NULL if not found + * \brief Find and delete an item identified by a string from the table + * \param *prb Pointer to the hash table + * \param *pId Pointer to the identifier + * \return Item's payload pointer, or NULL if not found */ epicsShareFunc void * epicsShareAPI bucketLookupAndRemoveItemStringId (BUCKET *prb, const char *pId); /** - * @name Status values returned by some bucketLib functions + * \name Status values returned by some bucketLib functions * @{ */ /** - * @brief A synonym for S_bucket_success + * \brief A synonym for S_bucket_success */ #define BUCKET_SUCCESS S_bucket_success /** - * @brief Success, must be 0. + * \brief Success, must be 0. */ #define S_bucket_success 0 /** - * @brief Memory allocation failed + * \brief Memory allocation failed */ #define S_bucket_noMemory (M_bucket | 1) /*Memory allocation failed*/ /** - * @brief Identifier already in use + * \brief Identifier already in use */ #define S_bucket_idInUse (M_bucket | 2) /*Identifier already in use*/ /** - * @brief Unknown identifier + * \brief Unknown identifier */ #define S_bucket_uknId (M_bucket | 3) /*Unknown identifier*/ /** @} */ diff --git a/modules/libcom/src/calc/postfix.h b/modules/libcom/src/calc/postfix.h index d811300ed..6bdbc1ae0 100644 --- a/modules/libcom/src/calc/postfix.h +++ b/modules/libcom/src/calc/postfix.h @@ -7,10 +7,10 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file postfix.h - * @author Bob Dalesio, Andrew Johnson + * \file postfix.h + * \author Bob Dalesio, Andrew Johnson * - * @brief The API for the EPICS Calculation Engine + * \brief The API for the EPICS Calculation Engine * * Defines macros and the routines provided by the calculation engine for * subsystems that need to evaluate mathematical expressions. @@ -21,50 +21,50 @@ #include "shareLib.h" -/** @brief Number of input arguments to a calc expression (A-L) */ +/** \brief Number of input arguments to a calc expression (A-L) */ #define CALCPERFORM_NARGS 12 -/** @brief Size of the internal partial result stack */ +/** \brief Size of the internal partial result stack */ #define CALCPERFORM_STACK 80 /** - * @name Postfix and Infix Buffer Sizes + * \name Postfix and Infix Buffer Sizes * @{ */ /** - * @brief Calculate required size of postfix buffer from infix + * \brief Calculate required size of postfix buffer from infix * * This macro calculates the maximum size of postfix buffer needed for an - * infix expression buffer of a given size. The argument @c n must count + * infix expression buffer of a given size. The argument \c n must count * the trailing nil byte in the input expression string. The actual size * needed is never larger than this value, although it is actually a * few bytes smaller for some sizes. * * The maximum expansion from infix to postfix is for the sub-expression - @code + \code .1?.1: -@endcode +\endcode * which is 6 characters long and results in 21 bytes of postfix: -@code +\code .1 => LITERAL_DOUBLE + 8 byte value ? => COND_IF .1 => LITERAL_DOUBLE + 8 byte value : => COND_ELSE ... => COND_END -@endcode +\endcode * For other short expressions the factor 21/6 always gives a big enough * postfix buffer (proven by hand, look at '1+' and '.1+' as well). */ #define INFIX_TO_POSTFIX_SIZE(n) ((n)*21/6) /** - * @brief Size of a "standard" infix string. + * \brief Size of a "standard" infix string. * * This is not a hard limit, just the default size for the database */ #define MAX_INFIX_SIZE 100 /** - * @brief Size of a "standard" postfix buffer. + * \brief Size of a "standard" postfix buffer. * * This is not a hard limit, just the default size for the database */ @@ -72,38 +72,38 @@ /** @} */ -/** @name Calc Engine Error Codes -* @note Changes in these errors must also be made in calcErrorStr(). +/** \name Calc Engine Error Codes +* \note Changes in these errors must also be made in calcErrorStr(). * @{ */ -/** @brief No error */ +/** \brief No error */ #define CALC_ERR_NONE 0 -/** @brief Too many results returned */ +/** \brief Too many results returned */ #define CALC_ERR_TOOMANY 1 -/** @brief Bad numeric literal */ +/** \brief Bad numeric literal */ #define CALC_ERR_BAD_LITERAL 2 -/** @brief Bad assignment target */ +/** \brief Bad assignment target */ #define CALC_ERR_BAD_ASSIGNMENT 3 -/** @brief Comma without parentheses */ +/** \brief Comma without parentheses */ #define CALC_ERR_BAD_SEPERATOR 4 -/** @brief Close parenthesis without open */ +/** \brief Close parenthesis without open */ #define CALC_ERR_PAREN_NOT_OPEN 5 -/** @brief Open parenthesis at end of expression */ +/** \brief Open parenthesis at end of expression */ #define CALC_ERR_PAREN_OPEN 6 -/** @brief Unbalanced conditional ?: operators */ +/** \brief Unbalanced conditional ?: operators */ #define CALC_ERR_CONDITIONAL 7 -/** @brief Incomplete expression, operand missing */ +/** \brief Incomplete expression, operand missing */ #define CALC_ERR_INCOMPLETE 8 -/** @brief Runtime stack would underflow */ +/** \brief Runtime stack would underflow */ #define CALC_ERR_UNDERFLOW 9 -/** @brief Runtime stack would overflow */ +/** \brief Runtime stack would overflow */ #define CALC_ERR_OVERFLOW 10 -/** @brief Syntax error */ +/** \brief Syntax error */ #define CALC_ERR_SYNTAX 11 -/** @brief NULL or empty input argument */ +/** \brief NULL or empty input argument */ #define CALC_ERR_NULL_ARG 12 -/** @brief Internal error, bad element type */ +/** \brief Internal error, bad element type */ #define CALC_ERR_INTERNAL 13 /** @} */ @@ -112,21 +112,21 @@ extern "C" { #endif -/** @brief Compile an infix expression into postfix byte-code +/** \brief Compile an infix expression into postfix byte-code * * Converts an expression from an infix string to postfix byte-code * - * @param pinfix Pointer to the infix string - * @param ppostfix Pointer to the postfix buffer - * @param perror Place to return an error code - * @return Non-zero value in event of error + * \param pinfix Pointer to the infix string + * \param ppostfix Pointer to the postfix buffer + * \param perror Place to return an error code + * \return Non-zero value in event of error * * It is the callers's responsibility to ensure that \c ppostfix points * to sufficient storage to hold the postfix expression. The macro * INFIX_TO_POSTFIX_SIZE(n) can be used to calculate an appropriate * postfix buffer size from the length of the infix buffer. * - * @note "n" must count the terminating nil byte too. + * \note "n" must count the terminating nil byte too. * * -# The **infix expressions** that can be used are very similar * to the C expression syntax, but with some additions and subtle @@ -230,7 +230,7 @@ extern "C" { * - Arccosine: acos(a) * - Arctangent: atan(a) * - 2 parameter arctangent: atan2(a, b) - * @note Note that these arguments are the reverse of the ANSI C function, + * \note Note that these arguments are the reverse of the ANSI C function, * so while C would return arctan(a/b) the calc expression engine returns arctan(b/a) * * -# ***Hyperbolic Trigonometry*** @@ -298,62 +298,62 @@ extern "C" { epicsShareFunc long postfix(const char *pinfix, char *ppostfix, short *perror); -/** @brief Run the calculation engine +/** \brief Run the calculation engine * * Evaluates the postfix expression against a set ot input values. * - * @param parg Pointer to an array of double values for the arguments A-L + * \param parg Pointer to an array of double values for the arguments A-L * that can appear in the expression. Note that the argument values may be * modified if the expression uses the assignment operator. - * @param presult Where to put the calculated result, which may be a NaN or Infinity. - * @param ppostfix The postfix expression created by postfix(). - * @return Status value 0 for OK, or non-zero if an error is discovered + * \param presult Where to put the calculated result, which may be a NaN or Infinity. + * \param ppostfix The postfix expression created by postfix(). + * \return Status value 0 for OK, or non-zero if an error is discovered * during the evaluation process. */ epicsShareFunc long calcPerform(double *parg, double *presult, const char *ppostfix); -/** @brief Find the inputs and outputs of an expression +/** \brief Find the inputs and outputs of an expression * * Software using the calc subsystem may need to know what expression * arguments are used and/or modified by a particular expression. It can * discover this from the postfix string by calling calcArgUsage(), which - * takes two pointers @c pinputs and @c pstores to a pair of unsigned long + * takes two pointers \c pinputs and \c pstores to a pair of unsigned long * bitmaps which return that information to the caller. Passing a NULL value * for either of these pointers is legal if only the other is needed. * - * The least signficant bit (bit 0) of the bitmap at @c *pinputs will be set + * The least signficant bit (bit 0) of the bitmap at \c *pinputs will be set * if the expression depends on the argument A, and so on through bit 11 for * the argument L. An argument that is not used until after a value has been * assigned to it will not be set in the pinputs bitmap, thus the bits can * be used to determine whether a value needs to be supplied for their * associated argument or not for the purposes of evaluating the expression. * - * Bit 0 of the bitmap at @c *pstores will be set if the expression assigns + * Bit 0 of the bitmap at \c *pstores will be set if the expression assigns * a value to the argument A, bit 1 for argument B etc. - * @param ppostfix A postfix expression created by postfix(). - * @param pinputs Bitmap pointer. - * @param pstores Bitmap pointer. - * @return The return value will be non-zero if the ppostfix expression was + * \param ppostfix A postfix expression created by postfix(). + * \param pinputs Bitmap pointer. + * \param pstores Bitmap pointer. + * \return The return value will be non-zero if the ppostfix expression was * illegal, otherwise 0. */ epicsShareFunc long calcArgUsage(const char *ppostfix, unsigned long *pinputs, unsigned long *pstores); -/** @brief Convert an error code to a string. +/** \brief Convert an error code to a string. * * Gives out a printable version of an individual error code. - * The error codes are macros defined here with names starting @c CALC_ERR_ - * @param error Error code - * @return A string representation of the error code + * The error codes are macros defined here with names starting \c CALC_ERR_ + * \param error Error code + * \return A string representation of the error code */ epicsShareFunc const char * calcErrorStr(short error); -/** @brief Disassemble a postfix expression +/** \brief Disassemble a postfix expression * * Convert the byte-code stream to text and print to stdout. - * @param pinst postfix instructions + * \param pinst postfix instructions */ epicsShareFunc void calcExprDump(const char *pinst); diff --git a/modules/libcom/src/cppStd/epicsAlgorithm.h b/modules/libcom/src/cppStd/epicsAlgorithm.h index b79732894..e2043cf26 100644 --- a/modules/libcom/src/cppStd/epicsAlgorithm.h +++ b/modules/libcom/src/cppStd/epicsAlgorithm.h @@ -7,12 +7,12 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file epicsAlgorithm.h - * @author Jeff Hill & Andrew Johnson + * \file epicsAlgorithm.h + * \author Jeff Hill & Andrew Johnson * - * @brief Contains a few templates out of the C++ standard header algorithm + * \brief Contains a few templates out of the C++ standard header algorithm * - * @note The templates are provided here in a much smaller file. Standard algorithm + * \note The templates are provided here in a much smaller file. Standard algorithm * contains many templates for sorting and searching through C++ template containers * which are not used in EPICS. If all you need from there is std::min(), * std::max() and/or std::swap() your code may compile faster if you include @@ -41,7 +41,7 @@ inline const T& epicsMin (const T& a, const T& b) /** * Returns the smaller of a or b compared using a @@ -53,7 +53,7 @@ inline const float& epicsMin (const float& a, const float& b) /** * Returns the smaller of a or b compared using a @@ -75,7 +75,7 @@ inline const T& epicsMax (const T& a, const T& b) /** * Returns the larger of a or b compared using a @@ -87,7 +87,7 @@ inline const float& epicsMax (const float& a, const float& b) /** * Returns the larger of a or b compared using a @@ -99,7 +99,7 @@ inline const double& epicsMax (const double& a, const double& b) /** * Swaps the values of a and b. * - * @note The data type must support both copy-construction and assignment. + * \note The data type must support both copy-construction and assignment. * */ template diff --git a/modules/libcom/src/dbmf/dbmf.h b/modules/libcom/src/dbmf/dbmf.h index d8f768a74..ef9787500 100644 --- a/modules/libcom/src/dbmf/dbmf.h +++ b/modules/libcom/src/dbmf/dbmf.h @@ -8,10 +8,10 @@ \*************************************************************************/ /** - * @file dbmf.h - * @author Jim Kowalkowski, Marty Kraimer + * \file dbmf.h + * \author Jim Kowalkowski, Marty Kraimer * - * @brief A library to manage storage that is allocated and quickly freed. + * \brief A library to manage storage that is allocated and quickly freed. * * Database Macro/Free describes a facility that prevents memory fragmentation * when temporary storage is being allocated and freed a short time later, at @@ -24,10 +24,10 @@ * - Between those calls to malloc() and free(), additional calls to * malloc() are made that do NOT have an associated free(). * - * @note In some environment, e.g. vxWorks, this behavior causes severe memory + * \note In some environment, e.g. vxWorks, this behavior causes severe memory * fragmentation. * - * @note This facility should NOT be used by code that allocates storage and + * \note This facility should NOT be used by code that allocates storage and * then keeps it for a considerable period of time before releasing. Such code * should consider using the freeList library. */ @@ -42,67 +42,67 @@ extern "C" { #endif /** - * @brief Initialize the facility - * @param size The maximum size request from dbmfMalloc() that will be + * \brief Initialize the facility + * \param size The maximum size request from dbmfMalloc() that will be * allocated from the dbmf pool (Size is always made a multiple of 8). - * @param chunkItems Each time malloc() must be called size*chunkItems bytes + * \param chunkItems Each time malloc() must be called size*chunkItems bytes * are allocated. - * @return 0 on success, -1 if already initialized + * \return 0 on success, -1 if already initialized * - * @note If dbmfInit() is not called before one of the other routines then it + * \note If dbmfInit() is not called before one of the other routines then it * is automatically called with size=64 and chunkItems=10 */ epicsShareFunc int dbmfInit(size_t size, int chunkItems); /** - * @brief Allocate memory. - * @param bytes If bytes > size then malloc() is used to allocate the memory. - * @return Pointer to the newly-allocated memory, or NULL on failure. + * \brief Allocate memory. + * \param bytes If bytes > size then malloc() is used to allocate the memory. + * \return Pointer to the newly-allocated memory, or NULL on failure. */ epicsShareFunc void * dbmfMalloc(size_t bytes); /** - * @brief Duplicate a string. + * \brief Duplicate a string. * * Create a copy of the input string. - * @param str Pointer to the null-terminated string to be copied. - * @return A pointer to the new copy, or NULL on failure. + * \param str Pointer to the null-terminated string to be copied. + * \return A pointer to the new copy, or NULL on failure. */ epicsShareFunc char * dbmfStrdup(const char *str); /** - * @brief Duplicate a string (up to len bytes). + * \brief Duplicate a string (up to len bytes). * * Copy at most len bytes of the input string into a new buffer. If no nil - * terminator is seen in the first @c len bytes a nil terminator is added. - * @param str Pointer to the null-terminated string to be copied. - * @param len Max number of bytes to copy. - * @return A pointer to the new string, or NULL on failure. + * terminator is seen in the first \c len bytes a nil terminator is added. + * \param str Pointer to the null-terminated string to be copied. + * \param len Max number of bytes to copy. + * \return A pointer to the new string, or NULL on failure. */ epicsShareFunc char * dbmfStrndup(const char *str, size_t len); /** - * @brief Concatenate three strings. + * \brief Concatenate three strings. * Returns a pointer to a null-terminated string made by concatenating the * three input strings. - * @param lhs Start string to which the others get concatenated to (left part). - * @param mid Next string to be concatenated to the lhs (mid part). - * @param rhs Last string to be concatenated to the lhs+mid (right part). - * @return A pointer to the new string, or NULL on failure. + * \param lhs Start string to which the others get concatenated to (left part). + * \param mid Next string to be concatenated to the lhs (mid part). + * \param rhs Last string to be concatenated to the lhs+mid (right part). + * \return A pointer to the new string, or NULL on failure. */ epicsShareFunc char * dbmfStrcat3(const char *lhs, const char *mid, const char *rhs); /** - * @brief Free the memory allocated by dbmfMalloc. - * @param bytes Pointer to memory obtained from dbmfMalloc(), dbmfStrdup(), + * \brief Free the memory allocated by dbmfMalloc. + * \param bytes Pointer to memory obtained from dbmfMalloc(), dbmfStrdup(), * dbmfStrndup() or dbmfStrcat3(). */ epicsShareFunc void dbmfFree(void *bytes); /** - * @brief Free all chunks that contain only free items. + * \brief Free all chunks that contain only free items. */ epicsShareFunc void dbmfFreeChunks(void); /** - * @brief Show the status of the dbmf memory pool. - * @param level Detail level. - * @return 0. + * \brief Show the status of the dbmf memory pool. + * \param level Detail level. + * \return 0. */ epicsShareFunc int dbmfShow(int level); diff --git a/modules/libcom/src/ellLib/ellLib.h b/modules/libcom/src/ellLib/ellLib.h index 776f556f4..8448fee2d 100644 --- a/modules/libcom/src/ellLib/ellLib.h +++ b/modules/libcom/src/ellLib/ellLib.h @@ -7,16 +7,16 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file ellLib.h - * @author John Winans (ANL) - * @author Andrew Johnson (ANL) + * \file ellLib.h + * \author John Winans (ANL) + * \author Andrew Johnson (ANL) * - * @brief A doubly-linked list library + * \brief A doubly-linked list library * * This provides similar functionality to the VxWorks lstLib library. * * Supports the creation and maintenance of a doubly-linked list. The user - * supplies a list descriptor (type ELLLIST) that will contain pointers to + * supplies a list descriptor (type \c ELLLIST) that will contain pointers to * the first and last nodes in the list, and a count of the number of * nodes in the list. The nodes in the list can be any user-defined structure, * but they must reserve space for two pointers as their first elements. @@ -32,9 +32,9 @@ extern "C" { #endif -/** @brief List node type. +/** \brief List node type. * - * A list node (@c ELLNODE) must be embedded in the structure to be placed + * A list node (an \c ELLNODE) must be embedded in the structure to be placed * on the list, ideally as the first member of that structure. * * If the node is elsewhere in the structure, care must be taken to convert @@ -43,26 +43,26 @@ extern "C" { * cannot be used with such a list. */ typedef struct ELLNODE { - struct ELLNODE *next; /**< @brief Pointer to next node in list */ - struct ELLNODE *previous; /**< @brief Pointer to previous node in list */ + struct ELLNODE *next; /**< \brief Pointer to next node in list */ + struct ELLNODE *previous; /**< \brief Pointer to previous node in list */ } ELLNODE; -/** @brief Value of a terminal node +/** \brief Value of a terminal node */ #define ELLNODE_INIT {NULL, NULL} -/** @brief List header type +/** \brief List header type */ typedef struct ELLLIST { - ELLNODE node; /**< @brief Pointers to the first and last nodes on list */ - int count; /**< @brief Number of nodes on the list */ + ELLNODE node; /**< \brief Pointers to the first and last nodes on list */ + int count; /**< \brief Number of nodes on the list */ } ELLLIST; -/** @brief Value of an empty list +/** \brief Value of an empty list */ #define ELLLIST_INIT {ELLNODE_INIT, 0} -/** @brief Pointer to free() for use by ellFree() macro. +/** \brief Pointer to free() for use by ellFree() macro. * * This is required for use on Windows, where each DLL has its own free() * function. The ellFree() macro passes the application's version of free() @@ -70,146 +70,143 @@ typedef struct ELLLIST { */ typedef void (*FREEFUNC)(void *); -/** @brief Initialize a list type - * @param PLIST Pointer to list header to be initialized +/** \brief Initialize a list type + * \param PLIST Pointer to list header to be initialized */ #define ellInit(PLIST) {\ (PLIST)->node.next = (PLIST)->node.previous = NULL;\ (PLIST)->count = 0;\ } -/** @brief Report the number of nodes in a list - * @param PLIST Pointer to list descriptor - * @return Number of nodes in the list +/** \brief Report the number of nodes in a list + * \param PLIST Pointer to list descriptor + * \return Number of nodes in the list */ #define ellCount(PLIST) ((PLIST)->count) -/** @brief Find the first node in list - * @param PLIST Pointer to list descriptor - * @return Pointer to first node in the list +/** \brief Find the first node in list + * \param PLIST Pointer to list descriptor + * \return Pointer to first node in the list */ #define ellFirst(PLIST) ((PLIST)->node.next) -/** @brief Find the last node in list - * @param PLIST Pointer to list descriptor - * @return Pointer to last node in the list +/** \brief Find the last node in list + * \param PLIST Pointer to list descriptor + * \return Pointer to last node in the list */ #define ellLast(PLIST) ((PLIST)->node.previous) -/** @brief Find the next node in list - * @param PNODE Pointer to node whose successor is to be found - * @return Pointer to the node following @c PNODE +/** \brief Find the next node in list + * \param PNODE Pointer to node whose successor is to be found + * \return Pointer to the node following \c PNODE */ #define ellNext(PNODE) ((PNODE)->next) -/** @brief Find the previous node in list - * @param PNODE Pointer to node whose predecessor is to be found - * @return Pointer to the node prior to @c PNODE +/** \brief Find the previous node in list + * \param PNODE Pointer to node whose predecessor is to be found + * \return Pointer to the node prior to \c PNODE */ #define ellPrevious(PNODE) ((PNODE)->previous) -/** @brief Free up the list - * @param PLIST List for which to free all nodes +/** \brief Free up the list + * \param PLIST List for which to free all nodes */ #define ellFree(PLIST) ellFree2(PLIST, free) /** - * @brief Adds a node to the end of a list - * @param pList Pointer to list descriptor - * @param pNode Pointer to node to be added + * \brief Adds a node to the end of a list + * \param pList Pointer to list descriptor + * \param pNode Pointer to node to be added */ epicsShareFunc void ellAdd (ELLLIST *pList, ELLNODE *pNode); /** - * @brief Concatenates a list to the end of another list. + * \brief Concatenates a list to the end of another list. * The list to be added is left empty. Either list (or both) * can be empty at the beginning of the operation. - * @param pDstList Destination list - * @param pAddList List to be added to @c pDstList + * \param pDstList Destination list + * \param pAddList List to be added to \c pDstList */ epicsShareFunc void ellConcat (ELLLIST *pDstList, ELLLIST *pAddList); /** - * @brief Deletes a node from a list. - * @param pList Pointer to list descriptor - * @param pNode Pointer to node to be deleted + * \brief Deletes a node from a list. + * \param pList Pointer to list descriptor + * \param pNode Pointer to node to be deleted */ epicsShareFunc void ellDelete (ELLLIST *pList, ELLNODE *pNode); /** - * @brief Extract a sublist from a list. - * @param pSrcList Pointer to source list - * @param pStartNode First node in @c pSrcList to be extracted - * @param pEndNode Last node in @c pSrcList to be extracted - * @param pDstList Pointer to list where to put extracted list + * \brief Extract a sublist from a list. + * \param pSrcList Pointer to source list + * \param pStartNode First node in \c pSrcList to be extracted + * \param pEndNode Last node in \c pSrcList to be extracted + * \param pDstList Pointer to list where to put extracted list */ epicsShareFunc void ellExtract (ELLLIST *pSrcList, ELLNODE *pStartNode, ELLNODE *pEndNode, ELLLIST *pDstList); /** - * @brief Deletes and returns the first node from a list - * @param pList Pointer to list from which to get node - * @return Pointer to the first node from the list, or NULL if the list is empty + * \brief Deletes and returns the first node from a list + * \param pList Pointer to list from which to get node + * \return Pointer to the first node from the list, or NULL if the list is empty */ epicsShareFunc ELLNODE * ellGet (ELLLIST *pList); /** - * @brief Deletes and returns the last node from a list. - * @param pList Pointer to list from which to get node - * @return Pointer to the last node from the list, or NULL if the list is empty + * \brief Deletes and returns the last node from a list. + * \param pList Pointer to list from which to get node + * \return Pointer to the last node from the list, or NULL if the list is empty */ epicsShareFunc ELLNODE * ellPop (ELLLIST *pList); /** - * @brief Inserts a node into a list immediately after a specific node - * @param plist Pointer to list into which to insert node - * @param pPrev Pointer to the node after which to insert - * @param pNode Pointer to the node to be inserted - * @note If @c pPrev is NULL @c pNode will be inserted at the head of the list + * \brief Inserts a node into a list immediately after a specific node + * \param plist Pointer to list into which to insert node + * \param pPrev Pointer to the node after which to insert + * \param pNode Pointer to the node to be inserted + * \note If \c pPrev is NULL \c pNode will be inserted at the head of the list */ epicsShareFunc void ellInsert (ELLLIST *plist, ELLNODE *pPrev, ELLNODE *pNode); /** - * @brief Find the Nth node in a list - * @param pList Pointer to list from which to find node - * @param nodeNum Index of the node to be found - * @return Pointer to the element at index @c nodeNum in pList, or NULL if + * \brief Find the Nth node in a list + * \param pList Pointer to list from which to find node + * \param nodeNum Index of the node to be found + * \return Pointer to the element at index \c nodeNum in pList, or NULL if * there is no such node in the list. - * @note The first node has index 1. + * \note The first node has index 1. */ epicsShareFunc ELLNODE * ellNth (ELLLIST *pList, int nodeNum); /** - * @brief Find the list node @c nStep steps away from a specified node - * @param pNode The known node - * @param nStep How many steps to take, may be negative to step backwards - * @return Pointer to the node @c nStep nodes from @c pNode, or NULL if there + * \brief Find the list node \c nStep steps away from a specified node + * \param pNode The known node + * \param nStep How many steps to take, may be negative to step backwards + * \return Pointer to the node \c nStep nodes from \c pNode, or NULL if there * is no such node in the list. */ epicsShareFunc ELLNODE * ellNStep (ELLNODE *pNode, int nStep); /** - * @brief Find the index of a specific node in a list - * @param pList Pointer to list to search - * @param pNode Pointer to node to search for - * @return The node's index, or -1 if it cannot be found on the list. - * @note The first node has index 1. + * \brief Find the index of a specific node in a list + * \param pList Pointer to list to search + * \param pNode Pointer to node to search for + * \return The node's index, or -1 if it cannot be found on the list. + * \note The first node has index 1. */ epicsShareFunc int ellFind (ELLLIST *pList, ELLNODE *pNode); typedef int (*pListCmp)(const ELLNODE* A, const ELLNODE* B); /** - * @author Michael Davidsaver - * @date 2016 - * - * @brief Stable (MergeSort) of a given list. - * @param pList Pointer to list to be sorted - * @param pListCmp Compare function to be used - * @note The comparison function cmp(A,B) is expected + * \brief Stable (MergeSort) of a given list. + * \param pList Pointer to list to be sorted + * \param pListCmp Compare function to be used + * \note The comparison function cmp(A,B) is expected * to return -1 for AB. * - * @note Use of mergesort algorithm based on analysis by + * \note Use of mergesort algorithm based on analysis by * http://www.chiark.greenend.org.uk/~sgtatham/algorithms/listsort.html */ epicsShareFunc void ellSortStable(ELLLIST *pList, pListCmp pListCmp); /** - * @brief Free all the nodes in a list. + * \brief Free all the nodes in a list. * * This routine empties a list, calling freeFunc() for every node on it. - * @param pList List from which to free all nodes - * @param freeFunc The free() routine to be called - * @note The nodes in the list are free()'d on the assumption that the node + * \param pList List from which to free all nodes + * \param freeFunc The free() routine to be called + * \note The nodes in the list are free()'d on the assumption that the node * structures were malloc()'d one-at-a-time and that the ELLNODE structure is * the first member of the parent structure. */ epicsShareFunc void ellFree2 (ELLLIST *pList, FREEFUNC freeFunc); /** - * @brief Verifies that the list is consistent - * @param pList List to be verified + * \brief Verifies that the list is consistent + * \param pList List to be verified */ epicsShareFunc void ellVerify (ELLLIST *pList); diff --git a/modules/libcom/src/env/envDefs.h b/modules/libcom/src/env/envDefs.h index 12dd601b5..7f4859063 100644 --- a/modules/libcom/src/env/envDefs.h +++ b/modules/libcom/src/env/envDefs.h @@ -8,10 +8,10 @@ \*************************************************************************/ /** - * @file envDefs.h - * @author Roger A. Cole + * \file envDefs.h + * \author Roger A. Cole * - * @brief Routines to get and set EPICS environment parameters. + * \brief Routines to get and set EPICS environment parameters. * * This file defines environment parameters used by EPICS and the * routines used to get and set those parameter values. @@ -23,7 +23,7 @@ * own use--the only caveat is that such parameters aren't automatically * setup by EPICS. * - * @note bldEnvData.pl looks for "epicsShareExtern const ENV_PARAM ;" + * \note bldEnvData.pl looks for "epicsShareExtern const ENV_PARAM ;" */ #ifndef envDefsH @@ -36,11 +36,11 @@ extern "C" { #include "shareLib.h" /** - * @brief A structure to hold a single environment parameter + * \brief A structure to hold a single environment parameter */ typedef struct envParam { - char *name; /**< @brief Name of the parameter */ - char *pdflt; /**< @brief Default value */ + char *name; /**< \brief Name of the parameter */ + char *pdflt; /**< \brief Default value */ } ENV_PARAM; epicsShareExtern const ENV_PARAM EPICS_CA_ADDR_LIST; @@ -58,7 +58,7 @@ epicsShareExtern const ENV_PARAM EPICS_CAS_IGNORE_ADDR_LIST; epicsShareExtern const ENV_PARAM EPICS_CAS_AUTO_BEACON_ADDR_LIST; epicsShareExtern const ENV_PARAM EPICS_CAS_BEACON_ADDR_LIST; epicsShareExtern const ENV_PARAM EPICS_CAS_SERVER_PORT; -epicsShareExtern const ENV_PARAM EPICS_CA_BEACON_PERIOD; /**< @brief deprecated */ +epicsShareExtern const ENV_PARAM EPICS_CA_BEACON_PERIOD; /**< \brief deprecated */ epicsShareExtern const ENV_PARAM EPICS_CAS_BEACON_PERIOD; epicsShareExtern const ENV_PARAM EPICS_CAS_BEACON_PORT; epicsShareExtern const ENV_PARAM EPICS_BUILD_COMPILER_CLASS; @@ -80,7 +80,7 @@ epicsShareExtern const ENV_PARAM *env_param_list[]; struct in_addr; /** - * @brief Get value of a configuration parameter + * \brief Get value of a configuration parameter * * Gets the value of a configuration parameter from the environment * and copies it into the caller's buffer. If the parameter isn't @@ -88,20 +88,20 @@ struct in_addr; * copied instead. If neither provides a non-empty string the buffer * is set to '\0' and NULL is returned. * - * @param pParam Pointer to config param structure. - * @param bufDim Dimension of parameter buffer - * @param pBuf Pointer to parameter buffer - * @return Pointer to the environment variable value string, or + * \param pParam Pointer to config param structure. + * \param bufDim Dimension of parameter buffer + * \param pBuf Pointer to parameter buffer + * \return Pointer to the environment variable value string, or * NULL if no parameter value and default value was empty. */ epicsShareFunc char * epicsShareAPI envGetConfigParam(const ENV_PARAM *pParam, int bufDim, char *pBuf); /** - * @brief Get a configuration parameter's value or default string. + * \brief Get a configuration parameter's value or default string. * - * @param pParam Pointer to config param structure. - * @return Pointer to the environment variable value string, or to + * \param pParam Pointer to config param structure. + * \return Pointer to the environment variable value string, or to * the default value for the parameter, or NULL if those strings * were empty or not set. */ @@ -109,16 +109,16 @@ epicsShareFunc const char * epicsShareAPI envGetConfigParamPtr(const ENV_PARAM *pParam); /** - * @brief Print the value of a configuration parameter. + * \brief Print the value of a configuration parameter. * - * @param pParam Pointer to config param structure. - * @return 0 + * \param pParam Pointer to config param structure. + * \return 0 */ epicsShareFunc long epicsShareAPI envPrtConfigParam(const ENV_PARAM *pParam); /** - * @brief Get value of an inet addr config parameter. + * \brief Get value of an inet addr config parameter. * * Gets the value of a configuration parameter and copies it into * the caller's (struct in_addr) buffer. If the configuration parameter @@ -129,67 +129,67 @@ epicsShareFunc long epicsShareAPI * If no parameter is found and there is no default, then -1 is * returned and the callers buffer is unmodified. * - * @param pParam Pointer to config param structure. - * @param pAddr Pointer to struct to receive inet addr. - * @return 0, or -1 if an error is encountered + * \param pParam Pointer to config param structure. + * \param pAddr Pointer to struct to receive inet addr. + * \return 0, or -1 if an error is encountered */ epicsShareFunc long epicsShareAPI envGetInetAddrConfigParam(const ENV_PARAM *pParam, struct in_addr *pAddr); /** - * @brief Get value of a double configuration parameter. + * \brief Get value of a double configuration parameter. * * Gets the value of a configuration parameter, converts it into a - * @c double value and copies that into the caller's buffer. If the + * \c double value and copies that into the caller's buffer. If the * configuration parameter isn't found in the environment, the * default value for the parameter is used instead. * * If no parameter is found and there is no default, then -1 is * returned and the callers buffer is unmodified. * - * @param pParam Pointer to config param structure. - * @param pDouble Pointer to place to store value. - * @return 0, or -1 if an error is encountered + * \param pParam Pointer to config param structure. + * \param pDouble Pointer to place to store value. + * \return 0, or -1 if an error is encountered */ epicsShareFunc long epicsShareAPI envGetDoubleConfigParam(const ENV_PARAM *pParam, double *pDouble); /** - * @brief Get value of a long configuration parameter. + * \brief Get value of a long configuration parameter. * * Gets the value of a configuration parameter, converts it into a - * @c long value and copies that into the caller's buffer. If the + * \c long value and copies that into the caller's buffer. If the * configuration parameter isn't found in the environment, the * default value for the parameter is used instead. * * If no parameter is found and there is no default, then -1 is * returned and the callers buffer is unmodified. * - * @param pParam Pointer to config param structure. - * @param pLong Pointer to place to store value. - * @return 0, or -1 if an error is encountered + * \param pParam Pointer to config param structure. + * \param pLong Pointer to place to store value. + * \return 0, or -1 if an error is encountered */ epicsShareFunc long epicsShareAPI envGetLongConfigParam(const ENV_PARAM *pParam, long *pLong); /** - * @brief Get value of a port number configuration parameter. + * \brief Get value of a port number configuration parameter. * * Returns the value of a configuration parameter that represents * an inet port number. If no environment variable is found the * default parameter value is used, and if that is also unset the - * @c defaultPort argument returned instead. The integer value must + * \c defaultPort argument returned instead. The integer value must * fall between the values IPPORT_USERRESERVED and USHRT_MAX or the - * @c defaultPort argument will be substituted instead. + * \c defaultPort argument will be substituted instead. * - * @param pEnv Pointer to config param structure. - * @param defaultPort Port number to be used if environment settings invalid. - * @return Port number. + * \param pEnv Pointer to config param structure. + * \param defaultPort Port number to be used if environment settings invalid. + * \return Port number. */ epicsShareFunc unsigned short epicsShareAPI envGetInetPortConfigParam (const ENV_PARAM *pEnv, unsigned short defaultPort); /** - * @brief Get value of a boolean configuration parameter. + * \brief Get value of a boolean configuration parameter. * * Gets the value of a configuration parameter, and puts the value * 0 or 1 into the caller's buffer depending on the value. If the @@ -203,38 +203,38 @@ epicsShareFunc unsigned short epicsShareAPI envGetInetPortConfigParam * If no parameter is found and there is no default, then -1 is * returned and the callers buffer is unmodified. * - * @param pParam Pointer to config param structure. - * @param pBool Pointer to place to store value. - * @return 0, or -1 if an error is encountered + * \param pParam Pointer to config param structure. + * \param pBool Pointer to place to store value. + * \return 0, or -1 if an error is encountered */ epicsShareFunc long epicsShareAPI envGetBoolConfigParam(const ENV_PARAM *pParam, int *pBool); /** - * @brief Prints all configuration parameters and their current value. + * \brief Prints all configuration parameters and their current value. * - * @return 0 + * \return 0 */ epicsShareFunc long epicsShareAPI epicsPrtEnvParams(void); /** - * @brief Set an environment variable's value + * \brief Set an environment variable's value * * The setenv() routine is not available on all operating systems. * This routine provides a portable alternative for all EPICS targets. - * @param name Environment variable name. - * @param value New value for environment variable. + * \param name Environment variable name. + * \param value New value for environment variable. */ epicsShareFunc void epicsShareAPI epicsEnvSet (const char *name, const char *value); /** - * @brief Clear the value of an environment variable - * @param name Environment variable name. + * \brief Clear the value of an environment variable + * \param name Environment variable name. */ epicsShareFunc void epicsShareAPI epicsEnvUnset (const char *name); /** - * @brief Print value of an environment variable, or all variables + * \brief Print value of an environment variable, or all variables * - * @param name Environment variable name, or NULL to show all. + * \param name Environment variable name, or NULL to show all. */ epicsShareFunc void epicsShareAPI epicsEnvShow (const char *name); diff --git a/modules/libcom/src/iocsh/iocsh.h b/modules/libcom/src/iocsh/iocsh.h index 4b87f3dd7..e69bd3c7b 100644 --- a/modules/libcom/src/iocsh/iocsh.h +++ b/modules/libcom/src/iocsh/iocsh.h @@ -85,27 +85,27 @@ epicsShareFunc const iocshVarDef * epicsShareAPI iocshFindVariable( /* This should only be called when iocsh is no longer needed*/ epicsShareFunc void epicsShareAPI iocshFree(void); -/** shorthand for @code iocshLoad(pathname, NULL) @endcode */ +/** shorthand for \code iocshLoad(pathname, NULL) \endcode */ epicsShareFunc int epicsShareAPI iocsh(const char *pathname); -/** shorthand for @code iocshRun(cmd, NULL) @endcode */ +/** shorthand for \code iocshRun(cmd, NULL) \endcode */ epicsShareFunc int epicsShareAPI iocshCmd(const char *cmd); /** Read and evaluate IOC shell commands from the given file. - * @param pathname Path to script file - * @param macros NULL or a comma seperated list of macro definitions. eg. "VAR1=x,VAR2=y" - * @return 0 on success, non-zero on error + * \param pathname Path to script file + * \param macros NULL or a comma seperated list of macro definitions. eg. "VAR1=x,VAR2=y" + * \return 0 on success, non-zero on error */ epicsShareFunc int epicsShareAPI iocshLoad(const char *pathname, const char* macros); /** Evaluate a single IOC shell command - * @param cmd Command string. eg. "echo \"something or other\"" - * @param macros NULL or a comma seperated list of macro definitions. eg. "VAR1=x,VAR2=y" - * @return 0 on success, non-zero on error + * \param cmd Command string. eg. "echo \"something or other\"" + * \param macros NULL or a comma seperated list of macro definitions. eg. "VAR1=x,VAR2=y" + * \return 0 on success, non-zero on error */ epicsShareFunc int epicsShareAPI iocshRun(const char *cmd, const char* macros); -/** @brief Signal error from an IOC shell function. +/** \brief Signal error from an IOC shell function. * - * @param err 0 - success (no op), !=0 - error - * @return The err argument value. + * \param err 0 - success (no op), !=0 - error + * \return The err argument value. */ epicsShareFunc int iocshSetError(int err); diff --git a/modules/libcom/src/macLib/macLib.h b/modules/libcom/src/macLib/macLib.h index 3be57cdce..8e75d3801 100644 --- a/modules/libcom/src/macLib/macLib.h +++ b/modules/libcom/src/macLib/macLib.h @@ -7,9 +7,9 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file macLib.h - * @brief Text macro substitution routines - * @author William Lupton, W. M. Keck Observatory + * \file macLib.h + * \brief Text macro substitution routines + * \author William Lupton, W. M. Keck Observatory * * This general purpose macro substitution library * is used for all macro substitutions in EPICS Base. @@ -31,31 +31,31 @@ extern "C" { #endif -/** @brief Maximum size of a macro name or value +/** \brief Maximum size of a macro name or value */ #define MAC_SIZE 256 -/** @brief Macro substitution context, for use by macLib routines only. +/** \brief Macro substitution context, for use by macLib routines only. * * An application may have multiple active contexts if desired. */ typedef struct { - long magic; /**< @brief magic number (used for authentication) */ - int dirty; /**< @brief values need expanding from raw values? */ - int level; /**< @brief scoping level */ - int debug; /**< @brief debugging level */ - ELLLIST list; /**< @brief macro name / value list */ - int flags; /**< @brief operating mode flags */ + long magic; /**< \brief magic number (used for authentication) */ + int dirty; /**< \brief values need expanding from raw values? */ + int level; /**< \brief scoping level */ + int debug; /**< \brief debugging level */ + ELLLIST list; /**< \brief macro name / value list */ + int flags; /**< \brief operating mode flags */ } MAC_HANDLE; -/** @name Core Library +/** \name Core Library * The core library provides a minimal set of basic operations. * @{ */ /** - * @brief Creates a new macro substitution context. - * @return 0 = OK; <0 = ERROR + * \brief Creates a new macro substitution context. + * \return 0 = OK; <0 = ERROR */ epicsShareFunc long epicsShareAPI macCreateHandle( @@ -64,16 +64,16 @@ epicsShareAPI macCreateHandle( const char * pairs[] /**< pointer to NULL-terminated array of {name,value} pair strings. A NULL - value implies undefined; a NULL @c pairs + value implies undefined; a NULL \c pairs argument implies no macros. */ ); /** - * @brief Disable or enable warning messages. + * \brief Disable or enable warning messages. * * The macExpandString() routine prints warnings when it cant expand a macro. * This routine can be used to silence those warnings. A non zero value will * suppress the warning messages from subsequent library routines given the - * same @c handle. + * same \c handle. */ epicsShareFunc void epicsShareAPI macSuppressWarning( @@ -83,15 +83,15 @@ epicsShareAPI macSuppressWarning( ); /** - * @brief Expand a string which may contain macro references. - * @return Returns the length of the expanded string, <0 if any macro are + * \brief Expand a string which may contain macro references. + * \return Returns the length of the expanded string, <0 if any macro are * undefined * - * This routine parses the @c src string looking for macro references and + * This routine parses the \c src string looking for macro references and * passes any it finds to macGetValue() for translation. * - * @note The return value is similar to that of macGetValue(). Its absolute - * value is the number of characters copied to @c dest. If the return value + * \note The return value is similar to that of macGetValue(). Its absolute + * value is the number of characters copied to \c dest. If the return value * is negative, at least one undefined macro was left unexpanded. */ epicsShareFunc long @@ -106,11 +106,11 @@ epicsShareAPI macExpandString( ); /** - * @brief Sets the value of a specific macro. - * @return Returns the length of the value string. - * @note If @c value is NULL, all instances of @c name are undefined at + * \brief Sets the value of a specific macro. + * \return Returns the length of the value string. + * \note If \c value is NULL, all instances of \c name are undefined at * all scoping levels (the named macro doesn't have to exist in this case). - * Macros referenced in @c value need not be defined at this point. + * Macros referenced in \c value need not be defined at this point. */ epicsShareFunc long epicsShareAPI macPutValue( @@ -122,22 +122,22 @@ epicsShareAPI macPutValue( ); /** - * @brief Returns the value of a macro - * @return Returns the length of the value string, <0 if undefined + * \brief Returns the value of a macro + * \return Returns the length of the value string, <0 if undefined * - * @c value will be zero-terminated if the length of the value is less than - * @c capacity. The return value is the number of characters copied to - * @c value (see below for behavior if the macro is undefined). If @c capacity - * is zero, no characters will be copied to @c value (which may be NULL) + * \c value will be zero-terminated if the length of the value is less than + * \c capacity. The return value is the number of characters copied to + * \c value (see below for behavior if the macro is undefined). If \c capacity + * is zero, no characters will be copied to \c value (which may be NULL) * and the call can be used to check whether the macro is defined. * - * @note Truncation of the value is not reported, applications should assume + * \note Truncation of the value is not reported, applications should assume * that truncation has occurred if the return value is equal to capacity. * * If the macro is undefined, the macro reference will be returned in * the value string (if permitted by maxlen) and the function value will * be _minus_ the number of characters copied. Note that treatment of - * @c capacity is intended to be consistent with the strncpy() routine. + * \c capacity is intended to be consistent with the strncpy() routine. * * If the value contains macro references, these references will be * expanded recursively. This expansion will detect a direct or indirect @@ -161,9 +161,9 @@ epicsShareAPI macGetValue( long capacity /**< capacity of destination buffer (value) */ ); /** - * @brief Marks a handle invalid, and frees all storage associated with it - * @return 0 = OK; <0 = ERROR - * @note Note that this does not free any strings into which macro values have + * \brief Marks a handle invalid, and frees all storage associated with it + * \return 0 = OK; <0 = ERROR + * \note Note that this does not free any strings into which macro values have * been returned. Macro values are always returned into strings which * were pre-allocated by the caller. */ @@ -172,8 +172,8 @@ epicsShareAPI macDeleteHandle( MAC_HANDLE *handle /**< opaque handle */ ); /** - * @brief Marks the start of a new scoping level - * @return 0 = OK; <0 = ERROR + * \brief Marks the start of a new scoping level + * \return 0 = OK; <0 = ERROR * * Marks all macro definitions added after this call as belonging * to another scope. These macros will be lost on a macPopScope() @@ -184,8 +184,8 @@ epicsShareAPI macPushScope( MAC_HANDLE *handle /**< opaque handle */ ); /** - * @brief Retrieve the last pushed scope (like stack operations) - * @return 0 = OK; <0 = ERROR + * \brief Retrieve the last pushed scope (like stack operations) + * \return 0 = OK; <0 = ERROR * * See macPushScope() */ @@ -194,8 +194,8 @@ epicsShareAPI macPopScope( MAC_HANDLE *handle /**< opaque handle */ ); /** - * @brief Reports details of current definitions - * @return 0 = OK; <0 = ERROR + * \brief Reports details of current definitions + * \return 0 = OK; <0 = ERROR * This sends details of current definitions to standard output, * and is intended purely for debugging purposes. */ @@ -205,15 +205,15 @@ epicsShareAPI macReportMacros( ); /** @} */ -/** @name Utility Library +/** \name Utility Library * These convenience functions are intended for applications to use and * provide a more convenient interface for some purposes. * @{ */ /** - * @brief Parse macro definitions into an array of {name, value} pairs. - * @return Number of macros found; <0 = ERROR + * \brief Parse macro definitions into an array of {name, value} pairs. + * \return Number of macros found; <0 = ERROR * * This takes a set of macro definitions in "a=xxx,b=yyy" format and * converts them into an array of pointers to character strings which @@ -251,8 +251,8 @@ epicsShareAPI macParseDefns( ); /** - * @brief Install set of {name, value} pairs as definitions - * @return Number of macros defined; <0 = ERROR + * \brief Install set of {name, value} pairs as definitions + * \return Number of macros defined; <0 = ERROR * * This takes an array of pairs as defined above and installs them as * definitions by calling macPutValue(). The pairs array is terminated @@ -269,8 +269,8 @@ epicsShareAPI macInstallMacros( ); /** - * @brief Expand environment variables in a string. - * @return Expanded string; NULL if any undefined macros were used. + * \brief Expand environment variables in a string. + * \return Expanded string; NULL if any undefined macros were used. * * This routine expands a string which may contain macros that are * environment variables. It parses the string looking for such @@ -285,8 +285,8 @@ epicsShareAPI macEnvExpand( ); /** - * @brief Expands macros and environment variables in a string. - * @return Expanded string; NULL if any undefined macros were used. + * \brief Expands macros and environment variables in a string. + * \return Expanded string; NULL if any undefined macros were used. * * This routine is similar to macEnvExpand() but allows an optional handle * to be passed in that may contain additional macro definitions. diff --git a/modules/libcom/src/misc/adjustment.h b/modules/libcom/src/misc/adjustment.h index f330bcd9d..c256569f1 100644 --- a/modules/libcom/src/misc/adjustment.h +++ b/modules/libcom/src/misc/adjustment.h @@ -9,8 +9,8 @@ \*************************************************************************/ /** - * @file adjustment.h - * @brief Declare function `adjustToWorstCaseAlignment` + * \file adjustment.h + * \brief Declare function `adjustToWorstCaseAlignment` * * Declares a single function `adjustToWorstCaseAlignment`. */ diff --git a/modules/libcom/src/misc/alarm.h b/modules/libcom/src/misc/alarm.h index fc6adedf6..edaaf1e5f 100644 --- a/modules/libcom/src/misc/alarm.h +++ b/modules/libcom/src/misc/alarm.h @@ -8,9 +8,9 @@ \*************************************************************************/ /** - * @file alarm.h - * @brief Alarm severity and status/condition values - * @author Bob Dalesio and Marty Kraimer + * \file alarm.h + * \brief Alarm severity and status/condition values + * \author Bob Dalesio and Marty Kraimer * * These alarm definitions must match the related * menuAlarmSevr.dbd and menuAlarmStat.dbd files @@ -27,13 +27,13 @@ extern "C" { #endif /** - * @brief The NO_ALARM value can be used as both a severity and a status. + * \brief The NO_ALARM value can be used as both a severity and a status. */ #define NO_ALARM 0 /** - * @brief Alarm severity values - * @note These must match the choices in menuAlarmSevr.dbd + * \brief Alarm severity values + * \note These must match the choices in menuAlarmSevr.dbd */ typedef enum { epicsSevNone = NO_ALARM, /**< No alarm */ @@ -44,7 +44,7 @@ typedef enum { } epicsAlarmSeverity; /** - * @name Original macros for alarm severity values + * \name Original macros for alarm severity values * @{ */ #define firstEpicsAlarmSev epicsSevNone @@ -55,8 +55,8 @@ typedef enum { /** @} */ /** - * @brief Alarm status/condition values - * @note These must match the choices in menuAlarmStat.dbd + * \brief Alarm status/condition values + * \note These must match the choices in menuAlarmStat.dbd */ typedef enum { epicsAlarmNone = NO_ALARM, /**< No alarm */ @@ -85,7 +85,7 @@ typedef enum { } epicsAlarmCondition; /** - * @name Original macros for alarm status/condition values + * \name Original macros for alarm status/condition values * @{ */ #define firstEpicsAlarmCond epicsAlarmNone @@ -114,11 +114,11 @@ typedef enum { /** @} */ /** - * @brief How to convert an alarm severity into a string + * \brief How to convert an alarm severity into a string */ epicsShareExtern const char *epicsAlarmSeverityStrings [ALARM_NSEV]; /** - * @brief How to convert an alarm condition/status into a string + * \brief How to convert an alarm condition/status into a string */ epicsShareExtern const char *epicsAlarmConditionStrings [ALARM_NSTATUS]; diff --git a/modules/libcom/src/misc/alarmString.h b/modules/libcom/src/misc/alarmString.h index 0ac92d74b..d2741b567 100644 --- a/modules/libcom/src/misc/alarmString.h +++ b/modules/libcom/src/misc/alarmString.h @@ -8,12 +8,12 @@ \*************************************************************************/ /** - * @file alarmString.h - * @brief Deprecated, use alarm.h instead + * \file alarmString.h + * \brief Deprecated, use alarm.h instead * * How to convert alarm status and severity values into a string for printing. * - * @note This file is deprecated, use alarm.h instead. + * \note This file is deprecated, use alarm.h instead. */ #ifndef INC_alarmString_H @@ -26,11 +26,11 @@ extern "C" { #endif /** - * @brief An alias for epicsAlarmSeverityStrings + * \brief An alias for epicsAlarmSeverityStrings */ #define alarmSeverityString epicsAlarmSeverityStrings /** - * @brief An alias for epicsAlarmConditionStrings + * \brief An alias for epicsAlarmConditionStrings */ #define alarmStatusString epicsAlarmConditionStrings diff --git a/modules/libcom/src/misc/cantProceed.h b/modules/libcom/src/misc/cantProceed.h index 4fa91811a..5fb3ef0f8 100644 --- a/modules/libcom/src/misc/cantProceed.h +++ b/modules/libcom/src/misc/cantProceed.h @@ -8,8 +8,8 @@ \*************************************************************************/ /** - * @file cantProceed.h - * @brief Routines for code that can't continue or return after an error. + * \file cantProceed.h + * \brief Routines for code that can't continue or return after an error. * * This is the EPICS equivalent of a Kernel Panic, except that the effect * is to halt only the thread that detects the error. @@ -33,19 +33,19 @@ extern "C" { #endif -/** @brief Suspend this thread, the caller cannot continue or return. +/** \brief Suspend this thread, the caller cannot continue or return. * * The effect of calling this is to print the error message followed by * the name of the thread that is being suspended. A stack trace will * also be shown if supported by the OS, and the thread is suspended * inside an infinite loop. - * @param errorMessage A printf-style error message describing the error. - * @param ... Any parameters required for the error message. + * \param errorMessage A printf-style error message describing the error. + * \param ... Any parameters required for the error message. */ epicsShareFunc void cantProceed(const char *errorMessage, ...) EPICS_PRINTF_STYLE(1,2); -/** @name Memory Allocation Functions +/** \name Memory Allocation Functions * These versions of calloc() and malloc() never fail, they suspend the * thread if the OS is unable to allocate the requested memory at the current * time. If the thread is resumed, they will re-try the memory allocation, @@ -54,18 +54,18 @@ epicsShareFunc void cantProceed(const char *errorMessage, ...) * gracefully when memory runs out. */ /** @{ */ -/** @brief A calloc() that never returns NULL. - * @param count Number of objects. - * @param size Size of each object. - * @param errorMessage What this memory is needed for. - * @return Pointer to zeroed allocated memory. +/** \brief A calloc() that never returns NULL. + * \param count Number of objects. + * \param size Size of each object. + * \param errorMessage What this memory is needed for. + * \return Pointer to zeroed allocated memory. */ epicsShareFunc void * callocMustSucceed(size_t count, size_t size, const char *errorMessage); -/** @brief A malloc() that never returns NULL. - * @param size Size of block to allocate. - * @param errorMessage What this memory is needed for. - * @return Pointer to allocated memory. +/** \brief A malloc() that never returns NULL. + * \param size Size of block to allocate. + * \param errorMessage What this memory is needed for. + * \return Pointer to allocated memory. */ epicsShareFunc void * mallocMustSucceed(size_t size, const char *errorMessage); /** @} */ diff --git a/modules/libcom/src/misc/dbDefs.h b/modules/libcom/src/misc/dbDefs.h index 16d3e06eb..5de0cd922 100644 --- a/modules/libcom/src/misc/dbDefs.h +++ b/modules/libcom/src/misc/dbDefs.h @@ -8,10 +8,10 @@ \*************************************************************************/ /** - * @file dbDefs.h - * @author Marty Kraimer + * \file dbDefs.h + * \author Marty Kraimer * - * @brief Miscellaneous macro definitions. + * \brief Miscellaneous macro definitions. * * This file defines several miscellaneous macros. */ @@ -31,30 +31,30 @@ #endif #define FALSE 0 -/** @brief Deprecated synonym for @c static */ +/** \brief Deprecated synonym for \c static */ #ifndef LOCAL # define LOCAL static #endif -/** @brief Number of elements in array */ +/** \brief Number of elements in array */ #ifndef NELEMENTS # define NELEMENTS(array) (sizeof (array) / sizeof ((array) [0])) #endif -/** @brief Deprecated synonym for @c offsetof */ +/** \brief Deprecated synonym for \c offsetof */ #ifndef OFFSET # define OFFSET(structure, member) offsetof(structure, member) #endif -/** @brief Find parent object from a member pointer +/** \brief Find parent object from a member pointer * * Subtracts the byte offset of the member in the structure from the * pointer to the member itself, giving a pointer to parent strucure. - * @param ptr Pointer to a member data field of a structure - * @param structure Type name of the parent structure - * @param member Field name of the data member - * @return Pointer to the parent structure - * @note Both GCC and Clang will type-check this macro. + * \param ptr Pointer to a member data field of a structure + * \param structure Type name of the parent structure + * \param member Field name of the data member + * \return Pointer to the parent structure + * \note Both GCC and Clang will type-check this macro. */ #ifndef CONTAINER # ifdef __GNUC__ @@ -68,18 +68,18 @@ # endif #endif -/** @brief Size of a record name including the nil terminator */ +/** \brief Size of a record name including the nil terminator */ #define PVNAME_STRINGSZ 61 -/** @brief Size of a record name without the nil terminator */ +/** \brief Size of a record name without the nil terminator */ #define PVNAME_SZ (PVNAME_STRINGSZ - 1) /** - * @def PVLINK_STRINGSZ - * @brief Buffer size for the string representation of a DBF_*LINK field + * \def PVLINK_STRINGSZ + * \brief Buffer size for the string representation of a DBF_*LINK field */ #define PVLINK_STRINGSZ 1024 -/** @brief dbAccess enums/menus can have up to this many choices */ +/** \brief dbAccess enums/menus can have up to this many choices */ #define DB_MAX_CHOICES 30 #endif /* INC_dbDefs_H */ diff --git a/modules/libcom/src/misc/epicsExit.h b/modules/libcom/src/misc/epicsExit.h index 0f1873f8d..23c40f8d1 100644 --- a/modules/libcom/src/misc/epicsExit.h +++ b/modules/libcom/src/misc/epicsExit.h @@ -8,9 +8,9 @@ \*************************************************************************/ /*epicsExit.h*/ /** - * @file epicsExit.h + * \file epicsExit.h * - * @brief Extended replacement for the Posix exit and atexit routines. + * \brief Extended replacement for the Posix exit and atexit routines. * * This is an extended replacement for the Posix exit and atexit routines, which * also provides a pointer argument to pass to the exit handlers. This facility @@ -28,61 +28,61 @@ extern "C" { #endif /** - * @brief Pointer to a callback function that is to be called + * \brief Pointer to a callback function that is to be called * by the epicsExit subsystem. */ typedef void (*epicsExitFunc)(void *arg); /** - * @brief Calls epicsExitCallAtExits(), then the OS exit() routine. - * @param status Passed to exit() + * \brief Calls epicsExitCallAtExits(), then the OS exit() routine. + * \param status Passed to exit() */ epicsShareFunc void epicsExit(int status); /** - * @brief Arrange to call epicsExit() later from a low priority thread. + * \brief Arrange to call epicsExit() later from a low priority thread. * * This delays the actual call to exit() so it doesn't run in this thread. - * @param status Passed to exit() + * \param status Passed to exit() */ epicsShareFunc void epicsExitLater(int status); /** - * @brief Internal routine that runs the registered exit routines. + * \brief Internal routine that runs the registered exit routines. * * Calls each of the functions registered by prior calls to epicsAtExit * in reverse order of their registration. - * @note Most applications will not call this routine directly. + * \note Most applications will not call this routine directly. */ epicsShareFunc void epicsExitCallAtExits(void); /** - * @brief Register a function and an associated context parameter - * @param func Function to be called when epicsExitCallAtExits is invoked. - * @param arg Context parameter for the function. - * @param name Function name + * \brief Register a function and an associated context parameter + * \param func Function to be called when epicsExitCallAtExits is invoked. + * \param arg Context parameter for the function. + * \param name Function name */ epicsShareFunc int epicsAtExit3(epicsExitFunc func, void *arg, const char* name); /** - * @brief Convenience macro to register a function and context value to be + * \brief Convenience macro to register a function and context value to be * run when the process exits. - * @param F Function to be called at process shutdown. - * @param A Context parameter for the function. + * \param F Function to be called at process shutdown. + * \param A Context parameter for the function. */ #define epicsAtExit(F,A) epicsAtExit3(F,A,#F) /** - * @brief Internal routine that runs the registered thread exit routines. + * \brief Internal routine that runs the registered thread exit routines. * * Calls each of the functions that were registered in the current thread by * calling epicsAtThreadExit(), in reverse order of their registration. - * @note This routine is called automatically when an epicsThread's main + * \note This routine is called automatically when an epicsThread's main * entry routine returns. It will not be run if the thread gets stopped by * some other method. */ epicsShareFunc void epicsExitCallAtThreadExits(void); /** - * @brief Register a function and an context value to be run by this thread + * \brief Register a function and an context value to be run by this thread * when it returns from its entry routine. - * @param func Function be called at thread completion. - * @param arg Context parameter for the function. + * \param func Function be called at thread completion. + * \param arg Context parameter for the function. */ epicsShareFunc int epicsAtThreadExit(epicsExitFunc func, void *arg); diff --git a/modules/libcom/src/misc/epicsExport.h b/modules/libcom/src/misc/epicsExport.h index 719555eaf..13b27b19e 100644 --- a/modules/libcom/src/misc/epicsExport.h +++ b/modules/libcom/src/misc/epicsExport.h @@ -11,8 +11,8 @@ #ifndef INC_epicsExport_H #define INC_epicsExport_H -/** @file epicsExport.h - * @brief Exporting IOC objects. +/** \file epicsExport.h + * \brief Exporting IOC objects. * * This header is unique, as it defines epicsExportSharedSymbols and thus * triggers a transition between importing declarations from other libraries, @@ -21,9 +21,9 @@ * * This header should be included with a trailing comment to make it stand * out from other includes, something like this: - @code + \code #include // defines epicsExportSharedSymbols - @endcode + \endcode */ #define epicsExportSharedSymbols @@ -35,82 +35,82 @@ extern "C" { typedef void (*REGISTRAR)(void); -/** @brief Generate a name for an export object. - * @param typ Object's data type. - * @param obj Object's name. - * @return C identifier for the export object. +/** \brief Generate a name for an export object. + * \param typ Object's data type. + * \param obj Object's name. + * \return C identifier for the export object. */ #define EPICS_EXPORT_POBJ(typ, obj) pvar_ ## typ ## _ ## obj -/** @brief Generate a name for an export function object. - * @param fun Function's name. - * @return C identifier for the export object. +/** \brief Generate a name for an export function object. + * \param fun Function's name. + * \return C identifier for the export object. */ #define EPICS_EXPORT_PFUNC(fun) EPICS_EXPORT_POBJ(func, fun) -/** @brief Declare an object for exporting. +/** \brief Declare an object for exporting. * * The epicsExportAddress() macro must be used to declare any IOC object * that is also named in a DBD file. For example a record support source * file must contain a statement like: - @code + \code epicsExportAddress(rset, myRSET); - @endcode + \endcode * * A device support source file must contain a statement like: - @code + \code epicsExportAddress(dset, devMyName); - @endcode - * Note that the @p typ parameter for a device support entry table must be - * spelled @c dset even if the @p obj was actually declared as some other - * type, say using @c typed_dset . + \endcode + * Note that the \p typ parameter for a device support entry table must be + * spelled \c dset even if the \p obj was actually declared as some other + * type, say using \c typed_dset . * * A driver support source file must contain a statement like: - @code + \code epicsExportAddress(drvet, drvName); - @endcode + \endcode * - * A variable named in a DBD @c variable statement must be declared with: - @code + * A variable named in a DBD \c variable statement must be declared with: + \code int myDebug = 0; epicsExportAddress(int, myDebug); - @endcode - * Only @c int and @c double are currently supported for DBD variables. + \endcode + * Only \c int and \c double are currently supported for DBD variables. * - * @param typ Object's data type. - * @param obj Object's name. + * \param typ Object's data type. + * \param obj Object's name. */ #define epicsExportAddress(typ, obj) \ epicsShareExtern typ *EPICS_EXPORT_POBJ(typ,obj); \ epicsShareDef typ *EPICS_EXPORT_POBJ(typ, obj) = (typ *) (char *) &obj -/** @brief Declare a registrar function for exporting. +/** \brief Declare a registrar function for exporting. * * The epicsExportRegistrar() macro must be used to declare a registrar * function that is named in a DBD \c registrar statement. For example: - @code + \code static void myRegistrar(void) { ... } epicsExportRegistrar(myRegistrar); - @endcode + \endcode * - * @param fun Registrar function's name. + * \param fun Registrar function's name. */ #define epicsExportRegistrar(fun) \ epicsShareFunc REGISTRAR EPICS_EXPORT_PFUNC(fun) = (REGISTRAR) &fun -/** @brief Declare and register a function for exporting. +/** \brief Declare and register a function for exporting. * * The epicsRegisterFunction() macro must be used to declare and register - * a function that is named in a DBD @c function statement and called by + * a function that is named in a DBD \c function statement and called by * one or more subroutine or aSub records. For example: - @code + \code epicsRegisterFunction(mySubInit); epicsRegisterFunction(mySubProcess); - @endcode + \endcode * - * @param fun Function's name + * \param fun Function's name */ #define epicsRegisterFunction(fun) \ static void register_func_ ## fun(void) \ diff --git a/modules/libcom/src/misc/epicsUnitTest.h b/modules/libcom/src/misc/epicsUnitTest.h index 28bb55dce..31aac6dc1 100644 --- a/modules/libcom/src/misc/epicsUnitTest.h +++ b/modules/libcom/src/misc/epicsUnitTest.h @@ -6,9 +6,9 @@ \*************************************************************************/ /** - * @file epicsUnitTest.h - * @brief Unit test routines - * @author Andrew Johnson + * \file epicsUnitTest.h + * \brief Unit test routines + * \author Andrew Johnson * * The unit test routines make it easy for a test program to generate output * that is compatible with the Test Anything Protocol and can thus be used with @@ -83,7 +83,7 @@ * IOC using iocBuildIsolated() or iocBuild(), it has to be started by calling * iocRun(). The suggested call sequence in a test program that needs to run the * IOC without Channel Access is: -@code +\code #include "iocInit.h" MAIN(iocTest) @@ -98,7 +98,7 @@ MAIN(iocTest) pdbbase = NULL; return testDone(); } -@endcode +\endcode * The part from iocBuildIsolated() to iocShutdown() can be repeated to * execute multiple tests within one executable or harness. @@ -113,7 +113,7 @@ MAIN(iocTest) * * The following is a simple example of a test program using the epicsUnitTest * routines: -@code +\code #include #include "epicsUnitTest.h" #include "testMain.h" @@ -127,10 +127,10 @@ MAIN(mathTest) testDiag("4 * atan(1) = %g", 4.0 * atan(1.0)); return testDone(); } -@endcode +\endcode * The output from running the above program looks like this: -@code +\code 1..3 ok 1 - Sine starts ok 2 - Cosine continues @@ -140,7 +140,7 @@ ok 3 - M_PI == 4.0*atan(1.0) ======= Tests: 3 Passed: 3 = 100% -@endcode +\endcode */ #ifndef INC_epicsUnitTest_H @@ -155,90 +155,90 @@ ok 3 - M_PI == 4.0*atan(1.0) extern "C" { #endif -/** @brief Declare the test plan, required. - * @param tests Number of tests to be run. May be zero if not known but the +/** \brief Declare the test plan, required. + * \param tests Number of tests to be run. May be zero if not known but the * test harness then can't tell if the program dies prematurely. */ epicsShareFunc void testPlan(int tests); -/** @name Announcing Test Results +/** \name Announcing Test Results * Routines that declare individual test results. */ /** @{ */ -/** @brief Test result with printf-style description. - * @param pass True/False value indicating result. - * @param fmt A printf-style format string describing the test. - * @param ... Any parameters required for the format string. - * @return The value of \p pass. +/** \brief Test result with printf-style description. + * \param pass True/False value indicating result. + * \param fmt A printf-style format string describing the test. + * \param ... Any parameters required for the format string. + * \return The value of \p pass. */ epicsShareFunc int testOk(int pass, const char *fmt, ...) EPICS_PRINTF_STYLE(2, 3); -/** @brief Test result using condition as description - * @param cond Condition to be evaluated and displayed. - * @return The value of \p cond. +/** \brief Test result using condition as description + * \param cond Condition to be evaluated and displayed. + * \return The value of \p cond. */ #define testOk1(cond) testOk(cond, "%s", #cond) -/** @brief Test result with var-args description. - * @param pass True/False value indicating result. - * @param fmt A printf-style format string describing the test. - * @param pvar A var-args pointer to any parameters for the format string. - * @return The value of \p pass. +/** \brief Test result with var-args description. + * \param pass True/False value indicating result. + * \param fmt A printf-style format string describing the test. + * \param pvar A var-args pointer to any parameters for the format string. + * \return The value of \p pass. */ epicsShareFunc int testOkV(int pass, const char *fmt, va_list pvar); -/** @brief Passing test result with printf-style description. - * @param fmt A printf-style format string describing the test. - * @param ... Any parameters required for the format string. - * @return The value of \p pass. +/** \brief Passing test result with printf-style description. + * \param fmt A printf-style format string describing the test. + * \param ... Any parameters required for the format string. + * \return The value of \p pass. */ epicsShareFunc void testPass(const char *fmt, ...) EPICS_PRINTF_STYLE(1, 2); -/** @brief Failing test result with printf-style description. - * @param fmt A printf-style format string describing the test. - * @param ... Any parameters required for the format string. +/** \brief Failing test result with printf-style description. + * \param fmt A printf-style format string describing the test. + * \param ... Any parameters required for the format string. */ epicsShareFunc void testFail(const char *fmt, ...) EPICS_PRINTF_STYLE(1, 2); /** @} */ -/** @name Missing or Failing Tests - * @brief Routines for handling special situations. +/** \name Missing or Failing Tests + * \brief Routines for handling special situations. */ /** @{ */ -/** @brief Place-holders for tests that can't be run. - * @param skip How many tests are being skipped. - * @param why Reason for skipping these tests. +/** \brief Place-holders for tests that can't be run. + * \param skip How many tests are being skipped. + * \param why Reason for skipping these tests. */ epicsShareFunc void testSkip(int skip, const char *why); -/** @brief Mark the start of a group of tests that are expected to fail - * @param why Reason for expected failures. +/** \brief Mark the start of a group of tests that are expected to fail + * \param why Reason for expected failures. */ epicsShareFunc void testTodoBegin(const char *why); -/** @brief Mark the end of a failing test group. +/** \brief Mark the end of a failing test group. */ epicsShareFunc void testTodoEnd(void); -/** @brief Stop testing, program cannot continue. - * @param fmt A printf-style format string giving the reason for stopping. - * @param ... Any parameters required for the format string. +/** \brief Stop testing, program cannot continue. + * \param fmt A printf-style format string giving the reason for stopping. + * \param ... Any parameters required for the format string. */ epicsShareFunc void testAbort(const char *fmt, ...) EPICS_PRINTF_STYLE(1, 2); /** @} */ -/** @brief Output additional diagnostics - * @param fmt A printf-style format string containing diagnostic information. - * @param ... Any parameters required for the format string. +/** \brief Output additional diagnostics + * \param fmt A printf-style format string containing diagnostic information. + * \param ... Any parameters required for the format string. */ epicsShareFunc int testDiag(const char *fmt, ...) EPICS_PRINTF_STYLE(1, 2); -/** @brief Mark the end of testing. +/** \brief Mark the end of testing. */ epicsShareFunc int testDone(void); epicsShareFunc int testImpreciseTiming(void); -/** @name Test Harness for Embedded OSs +/** \name Test Harness for Embedded OSs * These routines are used to create a test-harness that can run * multiple test programs, collect their names and results, then * display a summary at the end of testing. @@ -246,17 +246,17 @@ int testImpreciseTiming(void); /** @{ */ typedef int (*TESTFUNC)(void); -/** @brief Initialize test harness +/** \brief Initialize test harness */ epicsShareFunc void testHarness(void); epicsShareFunc void testHarnessExit(void *dummy); epicsShareFunc void runTestFunc(const char *name, TESTFUNC func); -/** @brief Run a test program - * @param func Name of the test program. +/** \brief Run a test program + * \param func Name of the test program. */ #define runTest(func) runTestFunc(#func, func) -/** @brief Declare all test programs finished +/** \brief Declare all test programs finished */ #define testHarnessDone() testHarnessExit(0) /** @} */ diff --git a/modules/libcom/src/misc/shareLib.h b/modules/libcom/src/misc/shareLib.h index 22f6fa235..108069781 100644 --- a/modules/libcom/src/misc/shareLib.h +++ b/modules/libcom/src/misc/shareLib.h @@ -7,8 +7,8 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file shareLib.h - * @brief Mark external symbols and entry points for shared libraries. + * \file shareLib.h + * \brief Mark external symbols and entry points for shared libraries. * * This is the header file for the "decorated names" that appear in * header files, e.g. @@ -35,7 +35,7 @@ * int epicsShareAPI myExtFunc ( int arg ); * int epicsShareAPI myExtFunc ( int arg ) {} * - * @note The epicsShareAPI attribute is deprecated and has been removed + * \note The epicsShareAPI attribute is deprecated and has been removed * from all IOC-specific APIs. Most libCom APIs still use it, but * it may get removed from these at some point in the future. * @@ -77,8 +77,8 @@ * which functions are exported from the DLL and which of them are imported * from other DLLs. * - * You must first @c \#include what you import and then @c \#define - * @c epicsExportSharedSymbols only right before you @c \#include the + * You must first \c \#include what you import and then \c \#define + * \c epicsExportSharedSymbols only right before you \c \#include the * prototypes for what you implement! You must include shareLib.h again each * time that the state of the import/export keywords changes, but this * usually occurs as a side effect of including the shareable libraries header diff --git a/modules/libcom/src/misc/unixFileName.h b/modules/libcom/src/misc/unixFileName.h index 9d7af252c..0b6edb92e 100644 --- a/modules/libcom/src/misc/unixFileName.h +++ b/modules/libcom/src/misc/unixFileName.h @@ -24,13 +24,13 @@ extern "C" { #define OSI_PATH_SEPARATOR "/" /** Return the absolute path of the current executable. - @returns NULL or the path. Caller must free() + \return NULL or the path. Caller must free() */ epicsShareFunc char *epicsGetExecName(void); /** Return the absolute path of the directory containing the current executable. - @returns NULL or the path. Caller must free() + \return NULL or the path. Caller must free() */ epicsShareFunc char *epicsGetExecDir(void); diff --git a/modules/libcom/src/osi/compilerDependencies.h b/modules/libcom/src/osi/compilerDependencies.h index dc089ced8..82c89322b 100644 --- a/modules/libcom/src/osi/compilerDependencies.h +++ b/modules/libcom/src/osi/compilerDependencies.h @@ -8,9 +8,9 @@ \*************************************************************************/ /** - * @file compilerDependencies.h - * @author Jeffrey O. Hill johill@lanl.gov - * @brief Compiler specific declarations + * \file compilerDependencies.h + * \author Jeffrey O. Hill johill@lanl.gov + * \brief Compiler specific declarations * */ diff --git a/modules/libcom/src/osi/devLib.h b/modules/libcom/src/osi/devLib.h index 8b0735058..0f263bd90 100644 --- a/modules/libcom/src/osi/devLib.h +++ b/modules/libcom/src/osi/devLib.h @@ -10,9 +10,9 @@ \*************************************************************************/ /** - * @file devLib.h - * @brief API for accessing hardware devices, originally over VMEbus - * @author Marty Kraimer and Jeff Hill + * \file devLib.h + * \brief API for accessing hardware devices, originally over VMEbus + * \author Marty Kraimer and Jeff Hill * * Support for allocation of common device resources */ @@ -20,111 +20,111 @@ #define EPICSDEVLIB_H /** - * @name Macros for normalizing values - * @warning Deprecated, we don't know of any code currently using these. + * \name Macros for normalizing values + * \warning Deprecated, we don't know of any code currently using these. * @{ */ -/** @brief Create a bit mask for a given number of bits */ +/** \brief Create a bit mask for a given number of bits */ #define devCreateMask(NBITS) ((1<<(NBITS))-1) -/** @brief Normalize a raw integer value and convert it to type double */ +/** \brief Normalize a raw integer value and convert it to type double */ #define devDigToNml(DIGITAL,NBITS) \ (((double)(DIGITAL))/devCreateMask(NBITS)) -/** @brief Convert a normalized value to a raw integer */ +/** \brief Convert a normalized value to a raw integer */ #define devNmlToDig(NORMAL,NBITS) \ (((long)(NORMAL)) * devCreateMask(NBITS)) /** @} */ /** - * @name Macros for pointer alignment - * @warning Deprecated, we don't know of any code currently using these. + * \name Macros for pointer alignment + * \warning Deprecated, we don't know of any code currently using these. * @{ */ -/** @brief Create an alignment mask for CTYPE */ +/** \brief Create an alignment mask for CTYPE */ #define devCreateAlignmentMask(CTYPE)\ (sizeof(CTYPE)>sizeof(double)?sizeof(double)-1:sizeof(CTYPE)-1) -/** @brief Check Pointer alignment, returns true if the pointer @c PTR +/** \brief Check Pointer alignment, returns true if the pointer \c PTR * is suitably aligned for its data type */ #define devPtrAlignTest(PTR) (!(devCreateAlignmentMask(*PTR)&(long)(PTR))) /** @} */ /** - * @name Error status values returned by devLib routines + * \name Error status values returned by devLib routines * @{ */ #define S_dev_success 0 -/** @brief Interrupt vector in use */ +/** \brief Interrupt vector in use */ #define S_dev_vectorInUse (M_devLib| 1) /*Interrupt vector in use*/ -/** @brief Interrupt vector install failed */ +/** \brief Interrupt vector install failed */ #define S_dev_vecInstlFail (M_devLib| 2) /*Interrupt vector install failed*/ -/** @brief Unrecognized interrupt type */ +/** \brief Unrecognized interrupt type */ #define S_dev_uknIntType (M_devLib| 3) /*Unrecognized interrupt type*/ -/** @brief Interrupt vector not in use by caller */ +/** \brief Interrupt vector not in use by caller */ #define S_dev_vectorNotInUse (M_devLib| 4) /*Interrupt vector not in use by caller*/ -/** @brief Invalid VME A16 address */ +/** \brief Invalid VME A16 address */ #define S_dev_badA16 (M_devLib| 5) /*Invalid VME A16 address*/ -/** @brief Invalid VME A24 address */ +/** \brief Invalid VME A24 address */ #define S_dev_badA24 (M_devLib| 6) /*Invalid VME A24 address*/ -/** @brief Invalid VME A32 address */ +/** \brief Invalid VME A32 address */ #define S_dev_badA32 (M_devLib| 7) /*Invalid VME A32 address*/ -/** @brief Unrecognized address space type */ +/** \brief Unrecognized address space type */ #define S_dev_uknAddrType (M_devLib| 8) /*Unrecognized address space type*/ -/** @brief Specified device address overlaps another device */ +/** \brief Specified device address overlaps another device */ #define S_dev_addressOverlap (M_devLib| 9) /*Specified device address overlaps another device*/ -/** @brief This device already owns the address range */ +/** \brief This device already owns the address range */ #define S_dev_identifyOverlap (M_devLib| 10) /*This device already owns the address range*/ -/** @brief Unable to map address */ +/** \brief Unable to map address */ #define S_dev_addrMapFail (M_devLib| 11) /*Unable to map address*/ -/** @brief Interrupt at vector disconnected from an EPICS device */ +/** \brief Interrupt at vector disconnected from an EPICS device */ #define S_dev_intDisconnect (M_devLib| 12) /*Interrupt at vector disconnected from an EPICS device*/ -/** @brief Internal failure */ +/** \brief Internal failure */ #define S_dev_internal (M_devLib| 13) /*Internal failure*/ -/** @brief Unable to enable interrupt level */ +/** \brief Unable to enable interrupt level */ #define S_dev_intEnFail (M_devLib| 14) /*Unable to enable interrupt level*/ -/** @brief Unable to disable interrupt level */ +/** \brief Unable to disable interrupt level */ #define S_dev_intDissFail (M_devLib| 15) /*Unable to disable interrupt level*/ -/** @brief Memory allocation failed */ +/** \brief Memory allocation failed */ #define S_dev_noMemory (M_devLib| 16) /*Memory allocation failed*/ -/** @brief Specified device address unregistered */ +/** \brief Specified device address unregistered */ #define S_dev_addressNotFound (M_devLib| 17) /*Specified device address unregistered*/ -/** @brief No device at specified address */ +/** \brief No device at specified address */ #define S_dev_noDevice (M_devLib| 18) /*No device at specified address*/ -/** @brief Wrong device type found at specified address */ +/** \brief Wrong device type found at specified address */ #define S_dev_wrongDevice (M_devLib| 19) /*Wrong device type found at specified address*/ -/** @brief Signal number (offset) to large */ +/** \brief Signal number (offset) to large */ #define S_dev_badSignalNumber (M_devLib| 20) /*Signal number (offset) to large*/ -/** @brief Signal count to large */ +/** \brief Signal count to large */ #define S_dev_badSignalCount (M_devLib| 21) /*Signal count to large*/ -/** @brief Device does not support requested operation */ +/** \brief Device does not support requested operation */ #define S_dev_badRequest (M_devLib| 22) /*Device does not support requested operation*/ -/** @brief Parameter too high */ +/** \brief Parameter too high */ #define S_dev_highValue (M_devLib| 23) /*Parameter too high*/ -/** @brief Parameter too low */ +/** \brief Parameter too low */ #define S_dev_lowValue (M_devLib| 24) /*Parameter too low*/ -/** @brief Specified address is ambiguous (more than one device responds) */ +/** \brief Specified address is ambiguous (more than one device responds) */ #define S_dev_multDevice (M_devLib| 25) /*Specified address is ambiguous (more than one device responds)*/ -/** @brief Device self test failed */ +/** \brief Device self test failed */ #define S_dev_badSelfTest (M_devLib| 26) /*Device self test failed*/ -/** @brief Device failed during initialization */ +/** \brief Device failed during initialization */ #define S_dev_badInit (M_devLib| 27) /*Device failed during initialization*/ -/** @brief Input exceeds Hardware Limit */ +/** \brief Input exceeds Hardware Limit */ #define S_dev_hdwLimit (M_devLib| 28) /*Input exceeds Hardware Limit*/ -/** @brief Unable to locate address space for device */ +/** \brief Unable to locate address space for device */ #define S_dev_deviceDoesNotFit (M_devLib| 29) /*Unable to locate address space for device*/ -/** @brief Device timed out */ +/** \brief Device timed out */ #define S_dev_deviceTMO (M_devLib| 30) /*Device timed out*/ -/** @brief Bad function pointer */ +/** \brief Bad function pointer */ #define S_dev_badFunction (M_devLib| 31) /*Bad function pointer*/ -/** @brief Bad interrupt vector */ +/** \brief Bad interrupt vector */ #define S_dev_badVector (M_devLib| 32) /*Bad interrupt vector*/ -/** @brief Bad function argument */ +/** \brief Bad function argument */ #define S_dev_badArgument (M_devLib| 33) /*Bad function argument*/ -/** @brief Invalid ISA address */ +/** \brief Invalid ISA address */ #define S_dev_badISA (M_devLib| 34) /*Invalid ISA address*/ -/** @brief Invalid VME CR/CSR address */ +/** \brief Invalid VME CR/CSR address */ #define S_dev_badCRCSR (M_devLib| 35) /*Invalid VME CR/CSR address*/ -/** @brief Synonym for S_dev_intEnFail */ +/** \brief Synonym for S_dev_intEnFail */ #define S_dev_vxWorksIntEnFail S_dev_intEnFail /** @} */ diff --git a/modules/libcom/src/osi/devLibVME.h b/modules/libcom/src/osi/devLibVME.h index 45db8f473..fbf8b399a 100644 --- a/modules/libcom/src/osi/devLibVME.h +++ b/modules/libcom/src/osi/devLibVME.h @@ -8,9 +8,9 @@ \*************************************************************************/ /** - * @file devLibVME.h - * @author Marty Kraimer, Jeff Hill - * @brief API for accessing hardware devices, mosty over VMEbus. + * \file devLibVME.h + * \author Marty Kraimer, Jeff Hill + * \brief API for accessing hardware devices, mosty over VMEbus. * * API for accessing hardware devices. The original APIs here were for * written for use with VMEbus but additional routines were added for @@ -36,17 +36,17 @@ extern "C" { #endif -/** @brief The available bus address types */ +/** \brief The available bus address types */ typedef enum { - atVMEA16, /**< @brief VME short I/O. */ - atVMEA24, /**< @brief VME standard I/O. */ - atVMEA32, /**< @brief VME extended I/O. */ - atISA, /**< @brief Memory mapped ISA access. */ - atVMECSR, /**< @brief VME-64 CR/CSR address space. */ - atLast /**< @brief Invalid, must be the last entry. */ + atVMEA16, /**< \brief VME short I/O. */ + atVMEA24, /**< \brief VME standard I/O. */ + atVMEA32, /**< \brief VME extended I/O. */ + atISA, /**< \brief Memory mapped ISA access. */ + atVMECSR, /**< \brief VME-64 CR/CSR address space. */ + atLast /**< \brief Invalid, must be the last entry. */ } epicsAddressType; -/** @brief A string representation of each of the bus address types */ +/** \brief A string representation of each of the bus address types */ epicsShareExtern const char *epicsAddressTypeName[]; #ifdef __cplusplus @@ -64,54 +64,54 @@ epicsShareExtern const char *epicsAddressTypeName[]; extern "C" { #endif -/** @brief Print a map of registered bus addresses. +/** \brief Print a map of registered bus addresses. * * Display a table of registsred bus address ranges, including the owner of * each registered address. - * @return 0, or an error status value + * \return 0, or an error status value */ epicsShareFunc long devAddressMap(void); -/** @brief Translate a bus address to a pointer the CPU can use. +/** \brief Translate a bus address to a pointer the CPU can use. * * Given a bus address, returns a pointer to that location in the CPU's * memory map, or an error if direct access isn't currently possible. - * @param addrType The bus address type. - * @param busAddr Bus address to be translated. - * @param *ppLocalAddr Where to put the CPU pointer. - * @return 0, or an error status value. + * \param addrType The bus address type. + * \param busAddr Bus address to be translated. + * \param *ppLocalAddr Where to put the CPU pointer. + * \return 0, or an error status value. */ epicsShareFunc long devBusToLocalAddr ( epicsAddressType addrType, size_t busAddr, volatile void **ppLocalAddr); -/** @brief Probe the bus for reading from a specific address. +/** \brief Probe the bus for reading from a specific address. * - * Performs a bus-error-safe @c wordSize atomic read from a specific + * Performs a bus-error-safe \c wordSize atomic read from a specific * address and returns an error if this caused a bus error. - * @param wordSize The word size to read: 1, 2, 4 or 8 bytes. - * @param ptr Pointer to the location in the CPU's memory map to read. - * @param pValueRead Where to put the value read. - * @return 0, or an error status value if the location could not be + * \param wordSize The word size to read: 1, 2, 4 or 8 bytes. + * \param ptr Pointer to the location in the CPU's memory map to read. + * \param pValueRead Where to put the value read. + * \return 0, or an error status value if the location could not be * accessed or the read caused a bus error. */ epicsShareFunc long devReadProbe ( unsigned wordSize, volatile const void *ptr, void *pValueRead); -/** @brief Read-probe a range of bus addresses, looking for empty space. +/** \brief Read-probe a range of bus addresses, looking for empty space. * * Verifies that no device responds at any naturally aligned addresses * within the given range. Tries to read every aligned address at every * word size between char and long over the entire range, returning * success only if none of the reads succeed. - * @warning This routine may be slow and have a very bad effect on a busy + * \warning This routine may be slow and have a very bad effect on a busy * VMEbus. Every read probe of an unused address will hold onto the VMEbus * for the global bus timeout period. - * @param addrType The bus address type. - * @param base First address base to probe. - * @param size Range of bus addresses to test, in bytes. - * @return 0 if no devices respond, or an error status value. + * \param addrType The bus address type. + * \param base First address base to probe. + * \param size Range of bus addresses to test, in bytes. + * \return 0 if no devices respond, or an error status value. */ epicsShareFunc long devNoResponseProbe( epicsAddressType addrType, @@ -119,32 +119,32 @@ epicsShareFunc long devNoResponseProbe( size_t size ); -/** @brief Probe the bus for writing to a specific address. +/** \brief Probe the bus for writing to a specific address. * - * Performs a bus-error-safe @c wordSize atomic write to a specific + * Performs a bus-error-safe \c wordSize atomic write to a specific * address and returns an error if this caused a bus error. - * @param wordSize The word size to write: 1, 2, 4 or 8 bytes. - * @param ptr Pointer to the location in the CPU's memory map to write to. - * @param pValueWritten The value to write. - * @return 0, or an error status value if the location could not be + * \param wordSize The word size to write: 1, 2, 4 or 8 bytes. + * \param ptr Pointer to the location in the CPU's memory map to write to. + * \param pValueWritten The value to write. + * \return 0, or an error status value if the location could not be * accessed or the write caused a bus error. */ epicsShareFunc long devWriteProbe ( unsigned wordSize, volatile void *ptr, const void *pValueWritten); -/** @brief Register a bus address range with a name. +/** \brief Register a bus address range with a name. * * The devLib code keeps a list of all bus address ranges registered with * this routine and returns an error if a later call attempts to register * any addresses that overlap with a range already registered. The call to * registering a range also converts the given base address into a pointer * in the CPU address space for the driver to use (see devBusToLocalAddr()). - * @param pOwnerName Name of a driver that will own this range. - * @param addrType The bus address type. - * @param logicalBaseAddress The bus start address. - * @param size Number of bytes to reserve. - * @param pPhysicalAddress Where to put the converted CPU pointer. - * @return 0, or an error status. + * \param pOwnerName Name of a driver that will own this range. + * \param addrType The bus address type. + * \param logicalBaseAddress The bus start address. + * \param size Number of bytes to reserve. + * \param pPhysicalAddress Where to put the converted CPU pointer. + * \return 0, or an error status. */ epicsShareFunc long devRegisterAddress( const char *pOwnerName, @@ -153,21 +153,21 @@ epicsShareFunc long devRegisterAddress( size_t size, volatile void **pPhysicalAddress); -/** @brief Release a bus address range previously registered. +/** \brief Release a bus address range previously registered. * * Release an address range that was previously registered by a call to * devRegisterAddress() or devAllocAddress(). - * @param addrType The bus address type. - * @param logicalBaseAddress The bus start address. - * @param pOwnerName The name of the driver that owns this range. - * @return 0, or an error status. + * \param addrType The bus address type. + * \param logicalBaseAddress The bus start address. + * \param pOwnerName The name of the driver that owns this range. + * \return 0, or an error status. */ epicsShareFunc long devUnregisterAddress( epicsAddressType addrType, size_t logicalBaseAddress, const char *pOwnerName); -/** @brief Allocate and register an unoccupied address block. +/** \brief Allocate and register an unoccupied address block. * * Asks devLib to allocate an address block of a particular address type. * This is useful for devices that appear in more than one address space @@ -175,15 +175,15 @@ epicsShareFunc long devUnregisterAddress( * in another window. As with devRegisterAddress() this call also converts * the new base address into a pointer in the CPU address space for the * driver to use (see devBusToLocalAddr()). - * @note This routine calls devNoResponseProbe() to find an unoccupied + * \note This routine calls devNoResponseProbe() to find an unoccupied * block in the bus address space, so using it may have a bad effect on a * busy VMEbus at allocation time; see the warning above. - * @param pOwnerName Name of a driver that will own this range. - * @param addrType The bus address type. - * @param size Number of bytes to be allocated. - * @param alignment How many low bits in the address must all be zero. - * @param pLocalAddress Where to put the CPU pointer. - * @return 0, or an error status value. + * \param pOwnerName Name of a driver that will own this range. + * \param addrType The bus address type. + * \param size Number of bytes to be allocated. + * \param alignment How many low bits in the address must all be zero. + * \param pLocalAddress Where to put the CPU pointer. + * \return 0, or an error status value. */ epicsShareFunc long devAllocAddress( const char *pOwnerName, @@ -192,11 +192,11 @@ epicsShareFunc long devAllocAddress( unsigned alignment, /*n ls bits zero in addr*/ volatile void **pLocalAddress); -/** @name VME Interrupt Management +/** \name VME Interrupt Management * Routines to manage VME interrupts. * @{ */ -/** @brief Connect an ISR up to a VME interrupt vector. +/** \brief Connect an ISR up to a VME interrupt vector. * * Interrupt Service Routines (ISRs) are normally written in C, and get * passed a context parameter given with them to this connection routine. @@ -206,105 +206,105 @@ epicsShareFunc long devAllocAddress( * epicsRingPointer.h and epicsTime.h for some APIs known to be suitable. * It is safest just to trigger a high-priority task to handle any * complex work that must happen as a result of the interrupt. - * @param vectorNumber VME interrupt vector number. - * @param pFunction The ISR to be called. - * @param parameter Context parameter for the ISR. - * @return 0, or an error status value. + * \param vectorNumber VME interrupt vector number. + * \param pFunction The ISR to be called. + * \param parameter Context parameter for the ISR. + * \return 0, or an error status value. */ epicsShareFunc long devConnectInterruptVME( unsigned vectorNumber, void (*pFunction)(void *), void *parameter); -/** @brief Disconnect an ISR from its VME interrupt vector. +/** \brief Disconnect an ISR from its VME interrupt vector. * * Device drivers may disconnect an ISR they connected earlier using this - * routine. In addition to taking the @c vectorNumber the ISR itself is + * routine. In addition to taking the \c vectorNumber the ISR itself is * required and used as a check to prevent a driver from inadvertently * removing an interrupt handler that it didn't install. * * On a PowerPC target running VxWorks, this routine will always return * with an error status. - * @param vectorNumber VME interrupt vector number. - * @param pFunction The ISR to be disconnected. - * @return 0, or an error status value. + * \param vectorNumber VME interrupt vector number. + * \param pFunction The ISR to be disconnected. + * \return 0, or an error status value. */ epicsShareFunc long devDisconnectInterruptVME( unsigned vectorNumber, void (*pFunction)(void *)); -/** @brief Determine if a VME interrupt vector is in use. +/** \brief Determine if a VME interrupt vector is in use. * * On a PowerPC target running VxWorks this routine will always return * false, indicating that a vector is unused. - * @param vectorNumber Interrupt vector number. - * @return True if vector has an ISR attached, otherwise false. + * \param vectorNumber Interrupt vector number. + * \return True if vector has an ISR attached, otherwise false. */ epicsShareFunc int devInterruptInUseVME (unsigned vectorNumber); -/** @brief Enable a VME interrupt level onto the CPU. +/** \brief Enable a VME interrupt level onto the CPU. * * The VMEbus allows multiple CPU boards to be installed in the same * backplane. When this is done, the differente VME interrupt levels * must be assigned to the CPUs since they cannot be shared. This * routine tells the VME interface that it should connect interrupts * from the indicated interrupt level to a CPU interrupt line. - * @param level VMEbus interrupt level to enable, 1-7. - * @return 0, or an error status value. + * \param level VMEbus interrupt level to enable, 1-7. + * \return 0, or an error status value. */ epicsShareFunc long devEnableInterruptLevelVME (unsigned level); -/** @brief Disable a VME interrupt level. +/** \brief Disable a VME interrupt level. * * This routine is the reverse of devEnableInterruptLevelVME(). - * @note This routine should not normally be used, even by a + * \note This routine should not normally be used, even by a * driver that enabled the interrupt level. Disabling a VME * interrupt level should only be done by software that knows * for certain that no other interrupting device is also using * that VME interrupt level. - * @param level VMEbus interrupt level to disable, 1-7. - * @return 0, or an error status value. + * \param level VMEbus interrupt level to disable, 1-7. + * \return 0, or an error status value. */ epicsShareFunc long devDisableInterruptLevelVME (unsigned level); /** @} */ -/** @name Memory for VME DMA Operations +/** \name Memory for VME DMA Operations * These routines manage memory that can be directly accessed * from the VMEbus in the A24 address space by another bus master * such as a DMA controller. * @{ */ -/** @brief malloc() for VME drivers that support DMA. +/** \brief malloc() for VME drivers that support DMA. * * Allocate memory of a given size from a region that can be * accessed from the VMEbus in the A24 address space. - * @param size How many bytes to allocate - * @return A pointer to the memory allocated, or NULL. + * \param size How many bytes to allocate + * \return A pointer to the memory allocated, or NULL. */ epicsShareFunc void *devLibA24Malloc(size_t size); -/** @brief calloc() for VME drivers that support DMA. +/** \brief calloc() for VME drivers that support DMA. * * Allocate and zero-fill a block of memory of a given size from * a region that can be accessed from the VMEbus in the A24 * address space. - * @param size How many bytes to allocate and zero. - * @return A pointer to the memory allocated, or NULL. + * \param size How many bytes to allocate and zero. + * \return A pointer to the memory allocated, or NULL. */ epicsShareFunc void *devLibA24Calloc(size_t size); -/** @brief free() for VME drivers that support DMA. +/** \brief free() for VME drivers that support DMA. * * Free a block of memory that was allocated using either * devLibA24Malloc() or devLibA24Calloc(). - * @param pBlock Block to be released. + * \param pBlock Block to be released. */ epicsShareFunc void devLibA24Free(void *pBlock); /** @} */ -/** @name ISA Interrupt Management +/** \name ISA Interrupt Management * Routines to manage ISAbus interrupts. - * @note These routines may not have been used for a very long time; + * \note These routines may not have been used for a very long time; * some appear to have never been implemented at all. They may vanish * with no notice from future versions of EPICS Base. Nobody is using * the PC's ISA-bus any more are they? @@ -313,11 +313,11 @@ epicsShareFunc void devLibA24Free(void *pBlock); /** * Connect ISR to a ISA interrupt. - * @warning Not implemented! - * @param interruptLevel Bus interrupt level to connect to. - * @param pFunction C function pointer to connect to. - * @param parameter Parameter to the called function. - * @return Returns success or error. + * \warning Not implemented! + * \param interruptLevel Bus interrupt level to connect to. + * \param pFunction C function pointer to connect to. + * \param parameter Parameter to the called function. + * \return Returns success or error. */ epicsShareFunc long devConnectInterruptISA( unsigned interruptLevel, @@ -326,10 +326,10 @@ epicsShareFunc long devConnectInterruptISA( /** * Disconnect ISR from a ISA interrupt level. - * @warning Not implemented! - * @param interruptLevel Interrupt level. - * @param pFunction C function pointer that was connected. - * @return returns success or error. + * \warning Not implemented! + * \param interruptLevel Interrupt level. + * \param pFunction C function pointer that was connected. + * \return returns success or error. */ epicsShareFunc long devDisconnectInterruptISA( unsigned interruptLevel, @@ -337,23 +337,23 @@ epicsShareFunc long devDisconnectInterruptISA( /** * Determine if an ISA interrupt level is in use - * @warning Not implemented! - * @param interruptLevel Interrupt level. - * @return Returns True/False. + * \warning Not implemented! + * \param interruptLevel Interrupt level. + * \return Returns True/False. */ epicsShareFunc int devInterruptLevelInUseISA (unsigned interruptLevel); /** * Enable ISA interrupt level - * @param level Interrupt level. - * @return Returns True/False. + * \param level Interrupt level. + * \return Returns True/False. */ epicsShareFunc long devEnableInterruptLevelISA (unsigned level); /** * Disable ISA interrupt level - * @param level Interrupt level. - * @return Returns True/False. + * \param level Interrupt level. + * \return Returns True/False. */ epicsShareFunc long devDisableInterruptLevelISA (unsigned level); /** @} */ @@ -361,13 +361,13 @@ epicsShareFunc long devDisableInterruptLevelISA (unsigned level); #ifndef NO_DEVLIB_OLD_INTERFACE /** - * @name Deprecated Interfaces + * \name Deprecated Interfaces * @{ */ typedef enum {intVME, intVXI, intISA} epicsInterruptType; /** - * @note This routine has been deprecated. It exists + * \note This routine has been deprecated. It exists * for backwards compatibility purposes only. * Please use one of devConnectInterruptVME(), devConnectInterruptPCI(), * devConnectInterruptISA() instead. devConnectInterrupt() will be removed @@ -380,7 +380,7 @@ epicsShareFunc long devConnectInterrupt( void *parameter); /** - * @note This routine has been deprecated. It exists + * \note This routine has been deprecated. It exists * for backwards compatibility purposes only. * Please use one of devDisconnectInterruptVME(), devDisconnectInterruptPCI(), * devDisconnectInterruptISA() instead. devDisconnectInterrupt() will @@ -392,7 +392,7 @@ epicsShareFunc long devDisconnectInterrupt( void (*pFunction)(void *)); /** - * @note This routine has been deprecated. It exists + * \note This routine has been deprecated. It exists * for backwards compatibility purposes only. * Please use one of devEnableInterruptLevelVME(), devEnableInterruptLevelPCI(), * devEnableInterruptLevelISA() instead. devEnableInterruptLevel() will @@ -402,7 +402,7 @@ epicsShareFunc long devEnableInterruptLevel( epicsInterruptType intType, unsigned level); /** - * @note This routine has been deprecated. It exists + * \note This routine has been deprecated. It exists * for backwards compatibility purposes only. * Please use one of devDisableInterruptLevelVME(), devDisableInterruptLevelISA(), * devDisableInterruptLevelPCI() instead. devDisableInterruptLevel() will @@ -412,7 +412,7 @@ epicsShareFunc long devDisableInterruptLevel ( epicsInterruptType intType, unsigned level); /** - * @note This routine has been deprecated. It exists + * \note This routine has been deprecated. It exists * for backwards compatibility purposes only. * Please use devNoResponseProbe() instead. locationProbe() will be removed * in a future release. diff --git a/modules/libcom/src/osi/devLibVMEImpl.h b/modules/libcom/src/osi/devLibVMEImpl.h index e3fd826f4..c9fea8d00 100644 --- a/modules/libcom/src/osi/devLibVMEImpl.h +++ b/modules/libcom/src/osi/devLibVMEImpl.h @@ -10,9 +10,9 @@ \*************************************************************************/ /** - * @file devLibVMEImpl.h - * @author Marty Kraimer, Jeff Hill - * @brief An interface from devLibVME.c to its OS-specific implementations. + * \file devLibVMEImpl.h + * \author Marty Kraimer, Jeff Hill + * \brief An interface from devLibVME.c to its OS-specific implementations. */ #ifndef INCdevLibImplh @@ -27,7 +27,7 @@ extern "C" { #endif /** - * @brief A table of function pointers for devLibVME implementations + * \brief A table of function pointers for devLibVME implementations * * The global virtual OS table \ref pdevLibVME controls * the behaviour of the functions defined in devLib.h. @@ -35,48 +35,48 @@ extern "C" { * to perform system specific tasks. */ typedef struct devLibVME { - /** @brief Map a bus address to the CPU's address space. */ + /** \brief Map a bus address to the CPU's address space. */ long (*pDevMapAddr) (epicsAddressType addrType, unsigned options, size_t logicalAddress, size_t size, volatile void **ppPhysicalAddress); - /** @brief Read a word, detect and protect against bus errors. */ + /** \brief Read a word, detect and protect against bus errors. */ long (*pDevReadProbe) (unsigned wordSize, volatile const void *ptr, void *pValueRead); - /** @brief Write a word, detect and protect against bus errors. */ + /** \brief Write a word, detect and protect against bus errors. */ long (*pDevWriteProbe) (unsigned wordSize, volatile void *ptr, const void *pValueWritten); - /** @brief Connect ISR to a VME interrupt vector. */ + /** \brief Connect ISR to a VME interrupt vector. */ long (*pDevConnectInterruptVME) (unsigned vectorNumber, void (*pFunction)(void *), void *parameter); - /** @brief Disconnect ISR from a VME interrupt vector. */ + /** \brief Disconnect ISR from a VME interrupt vector. */ long (*pDevDisconnectInterruptVME) (unsigned vectorNumber, void (*pFunction)(void *)); - /** @brief Enable VME interrupt level to CPU. */ + /** \brief Enable VME interrupt level to CPU. */ long (*pDevEnableInterruptLevelVME) (unsigned level); - /** @brief Disable VME interrupt level to CPU. */ + /** \brief Disable VME interrupt level to CPU. */ long (*pDevDisableInterruptLevelVME) (unsigned level); - /** @brief Malloc a block accessible from the VME A24 address space. */ + /** \brief Malloc a block accessible from the VME A24 address space. */ void *(*pDevA24Malloc)(size_t nbytes); - /** @brief Free a block allocated for the VME A24 address space. */ + /** \brief Free a block allocated for the VME A24 address space. */ void (*pDevA24Free)(void *pBlock); - /** @brief Init devLib */ + /** \brief Init devLib */ long (*pDevInit)(void); - /** @brief Check if interrupt vector has an ISR connected. */ + /** \brief Check if interrupt vector has an ISR connected. */ int (*pDevInterruptInUseVME)(unsigned vectorNumber); }devLibVME; -/** @brief Pointer to the entry table used by devLibVME routines. */ +/** \brief Pointer to the entry table used by devLibVME routines. */ epicsShareExtern devLibVME *pdevLibVME; #ifndef NO_DEVLIB_COMPAT -/** @brief An alias for pdevLibVME */ +/** \brief An alias for pdevLibVME */ # define pdevLibVirtualOS pdevLibVME -/** @brief A type definition for devLibVME */ +/** \brief A type definition for devLibVME */ typedef devLibVME devLibVirtualOS; #endif diff --git a/modules/libcom/src/osi/epicsAssert.h b/modules/libcom/src/osi/epicsAssert.h index df6d4593e..8df8a2e86 100644 --- a/modules/libcom/src/osi/epicsAssert.h +++ b/modules/libcom/src/osi/epicsAssert.h @@ -7,20 +7,20 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ -/**@file epicsAssert.h - * @author Jeffery O. Hill +/**\file epicsAssert.h + * \author Jeffery O. Hill * - * @brief An EPICS-specific replacement for ANSI C's assert. + * \brief An EPICS-specific replacement for ANSI C's assert. * * To use this version just include: - @code + \code #define epicsAssertAuthor "Code Author my@email.address" #include - @endcode + \endcode * instead of - @code + \code #include - @endcode + \endcode * * If an assert() fails, it calls errlog indicating the program's author, file name, and * line number. Under each OS there are specialized instructions assisting the user to @@ -34,7 +34,7 @@ * This header also provides a compile-time assertion macro STATIC_ASSERT() * which can be used to check a constant-expression at compile-time. The C or * C++ compiler will flag an error if the expresstion evaluates to 0. The - * STATIC_ASSERT() macro can only be used where a @c typedef is syntactically + * STATIC_ASSERT() macro can only be used where a \c typedef is syntactically * legal. **/ @@ -50,7 +50,7 @@ extern "C" { #ifndef epicsAssertAuthor -/**@brief Optional string giving the author's name */ +/**\brief Optional string giving the author's name */ # define epicsAssertAuthor 0 #endif @@ -64,8 +64,8 @@ extern "C" { epicsShareFunc void epicsAssert (const char *pFile, const unsigned line, const char *pExp, const char *pAuthorName); -/**@brief Declare that a condition should be true. - * @param exp Expression that should evaluate to True. +/**\brief Declare that a condition should be true. + * \param exp Expression that should evaluate to True. */ # define assert(exp) ((exp) ? (void)0 : \ epicsAssert(__FILE__, __LINE__, #exp, epicsAssertAuthor)) @@ -80,8 +80,8 @@ epicsShareFunc void epicsAssert (const char *pFile, const unsigned line, #define STATIC_JOIN(x, y) STATIC_JOIN2(x, y) #define STATIC_JOIN2(x, y) x ## y -/**@brief Declare a condition that should be true at compile-time. - * @param expr A C/C++ const-expression that should evaluate to True. +/**\brief Declare a condition that should be true at compile-time. + * \param expr A C/C++ const-expression that should evaluate to True. */ #define STATIC_ASSERT(expr) \ typedef int STATIC_JOIN(static_assert_failed_at_line_, __LINE__) \ diff --git a/modules/libcom/src/osi/epicsEvent.h b/modules/libcom/src/osi/epicsEvent.h index 50a7ee22a..c97cb4d8a 100644 --- a/modules/libcom/src/osi/epicsEvent.h +++ b/modules/libcom/src/osi/epicsEvent.h @@ -7,9 +7,9 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ -/**@file epicsEvent.h +/**\file epicsEvent.h * - * @brief APIs for the epicsEvent binary semaphore. + * \brief APIs for the epicsEvent binary semaphore. * * Defines the C++ and C API's for a simple binary semaphore. If multiple threads are * waiting on the same event, only one of them will be woken when the event is signalled. @@ -19,22 +19,22 @@ * For example: * * When creating the consumer thread also create an epicsEvent. - @code + \code epicsEvent *pevent = new epicsEvent; - @endcode + \endcode * The consumer thread has code containing: - @code + \code while(1) { pevent->wait(); while( {more work} ) { {process work} } } - @endcode + \endcode * Producers create requests and issue the statement: - @code + \code pevent->trigger(); - @endcode + \endcode **/ #ifndef epicsEventh @@ -42,24 +42,24 @@ #include "shareLib.h" -/** @brief An identifier for an epicsEvent for use with the C API */ +/** \brief An identifier for an epicsEvent for use with the C API */ typedef struct epicsEventOSD *epicsEventId; -/** @brief Return status from several C API routines. */ +/** \brief Return status from several C API routines. */ typedef enum { epicsEventOK = 0, epicsEventWaitTimeout, epicsEventError } epicsEventStatus; -/** @brief Old name provided for backwards compatibility */ +/** \brief Old name provided for backwards compatibility */ #define epicsEventWaitStatus epicsEventStatus -/** @brief Old name provided for backwards compatibility */ +/** \brief Old name provided for backwards compatibility */ #define epicsEventWaitOK epicsEventOK -/** @brief Old name provided for backwards compatibility */ +/** \brief Old name provided for backwards compatibility */ #define epicsEventWaitError epicsEventError -/** @brief Possible initial states of a new epicsEvent */ +/** \brief Possible initial states of a new epicsEvent */ typedef enum { epicsEventEmpty, epicsEventFull @@ -67,7 +67,7 @@ typedef enum { #ifdef __cplusplus -/**@brief A binary semaphore. +/**\brief A binary semaphore. * * An epicsEvent is a binary semaphore that can be empty or full. * When empty, a wait() issued before the next call to trigger() will block. @@ -77,39 +77,39 @@ typedef enum { **/ class epicsShareClass epicsEvent { public: - /**@brief Constructor. - * @param initial State when created, empty (the default) or full. + /**\brief Constructor. + * \param initial State when created, empty (the default) or full. **/ epicsEvent ( epicsEventInitialState initial = epicsEventEmpty ); - /**@brief Destroy the epicsEvent and any resources it holds. No calls to + /**\brief Destroy the epicsEvent and any resources it holds. No calls to * wait() can be active when this call is made. **/ ~epicsEvent (); - /**@brief Trigger the event i.e. ensures the next or current call to wait + /**\brief Trigger the event i.e. ensures the next or current call to wait * completes. This method may be called from a vxWorks or RTEMS interrupt * handler. **/ void trigger (); - /**@brief Signal is a synonym for trigger(). + /**\brief Signal is a synonym for trigger(). **/ void signal () { this->trigger(); } - /**@brief Wait for the event. - * @note Blocks until full. + /**\brief Wait for the event. + * \note Blocks until full. **/ void wait (); - /**@brief Wait for the event or until the specified timeout. - * @param timeOut The timeout delay in seconds. - * @return True if the event was triggered, False if it timed out. + /**\brief Wait for the event or until the specified timeout. + * \param timeOut The timeout delay in seconds. + * \return True if the event was triggered, False if it timed out. **/ bool wait ( double timeOut ); - /**@brief Similar to wait() except that if the event is currenly empty the + /**\brief Similar to wait() except that if the event is currenly empty the * call will return immediately. - * @return True if the event was full (triggered), False if empty. + * \return True if the event was full (triggered), False if empty. **/ bool tryWait (); - /**@brief Display information about the semaphore. - * @note The information displayed is architecture dependant. - * @param level An unsigned int for the level of information to be displayed. + /**\brief Display information about the semaphore. + * \note The information displayed is architecture dependant. + * \param level An unsigned int for the level of information to be displayed. **/ void show ( unsigned level ) const; @@ -123,90 +123,90 @@ private: extern "C" { #endif /*__cplusplus */ -/**@brief Create an epicsEvent for use from C code, or return NULL. +/**\brief Create an epicsEvent for use from C code, or return NULL. * - * @param initialState Starting state, @c epicsEventEmpty or @c epicsEventFull. - * @return An identifier for the new event, or NULL if one not be created. + * \param initialState Starting state, \c epicsEventEmpty or \c epicsEventFull. + * \return An identifier for the new event, or NULL if one not be created. **/ epicsShareFunc epicsEventId epicsEventCreate( epicsEventInitialState initialState); -/**@brief Create an epicsEvent for use from C code. +/**\brief Create an epicsEvent for use from C code. * * This routine does not return if the object could not be created. - * @param initialState Starting state, @c epicsEventEmpty or @c epicsEventFull. - * @return An identifier for the new event. + * \param initialState Starting state, \c epicsEventEmpty or \c epicsEventFull. + * \return An identifier for the new event. **/ epicsShareFunc epicsEventId epicsEventMustCreate ( epicsEventInitialState initialState); -/**@brief Destroy an epicsEvent and any resources it holds. +/**\brief Destroy an epicsEvent and any resources it holds. * * No calls to any epicsEventWait routines can be active when this call is made. - * @param id The event identifier. + * \param id The event identifier. **/ epicsShareFunc void epicsEventDestroy(epicsEventId id); -/**@brief Trigger an event i.e. ensures the next or current call to wait +/**\brief Trigger an event i.e. ensures the next or current call to wait * completes. * - * @note This method may be called from a VxWorks or RTEMS interrupt + * \note This method may be called from a VxWorks or RTEMS interrupt * handler. - * @param id The event identifier. - * @return Status indicator. + * \param id The event identifier. + * \return Status indicator. **/ epicsShareFunc epicsEventStatus epicsEventTrigger( epicsEventId id); -/**@brief Trigger an event. +/**\brief Trigger an event. * * This routine does not return if the identifier is invalid. - * @param id The event identifier. + * \param id The event identifier. */ epicsShareFunc void epicsEventMustTrigger(epicsEventId id); -/**@brief A synonym for epicsEventTrigger(). - * @param ID The event identifier. - * @return Status indicator. +/**\brief A synonym for epicsEventTrigger(). + * \param ID The event identifier. + * \return Status indicator. **/ #define epicsEventSignal(ID) epicsEventMustTrigger(ID) -/**@brief Wait for an event. - * @note Blocks until full. - * @param id The event identifier. - * @return Status indicator. +/**\brief Wait for an event. + * \note Blocks until full. + * \param id The event identifier. + * \return Status indicator. **/ epicsShareFunc epicsEventStatus epicsEventWait( epicsEventId id); -/**@brief Wait for an event (see epicsEventWait()). +/**\brief Wait for an event (see epicsEventWait()). * * This routine does not return if the identifier is invalid. - * @param id The event identifier. + * \param id The event identifier. */ epicsShareFunc void epicsEventMustWait(epicsEventId id); -/**@brief Wait an the event or until the specified timeout period is over. - * @note Blocks until full or timeout. - * @param id The event identifier. - * @param timeOut The timeout delay in seconds. - * @return Status indicator. +/**\brief Wait an the event or until the specified timeout period is over. + * \note Blocks until full or timeout. + * \param id The event identifier. + * \param timeOut The timeout delay in seconds. + * \return Status indicator. **/ epicsShareFunc epicsEventStatus epicsEventWaitWithTimeout( epicsEventId id, double timeOut); -/**@brief Similar to wait() except that if the event is currenly empty the - * call will return immediately with status @c epicsEventWaitTimeout. - * @param id The event identifier. - * @return Status indicator, @c epicsEventWaitTimeout when the event is empty. +/**\brief Similar to wait() except that if the event is currenly empty the + * call will return immediately with status \c epicsEventWaitTimeout. + * \param id The event identifier. + * \return Status indicator, \c epicsEventWaitTimeout when the event is empty. **/ epicsShareFunc epicsEventStatus epicsEventTryWait( epicsEventId id); -/**@brief Display information about the semaphore. - * @note The information displayed is architecture dependant. - * @param id The event identifier. - * @param level An unsigned int for the level of information to be displayed. +/**\brief Display information about the semaphore. + * \note The information displayed is architecture dependant. + * \param id The event identifier. + * \param level An unsigned int for the level of information to be displayed. **/ epicsShareFunc void epicsEventShow( epicsEventId id, unsigned int level); diff --git a/modules/libcom/src/osi/epicsGeneralTime.h b/modules/libcom/src/osi/epicsGeneralTime.h index 73304cfbc..8f494b376 100644 --- a/modules/libcom/src/osi/epicsGeneralTime.h +++ b/modules/libcom/src/osi/epicsGeneralTime.h @@ -7,9 +7,9 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ -/**@file epicsGeneralTime.h +/**\file epicsGeneralTime.h * - * @brief The generalTime framework provides a mechanism for several time providers to be + * \brief The generalTime framework provides a mechanism for several time providers to be * present within the system. * * There are two types of time provider, one type provides the current wall-clock @@ -28,7 +28,7 @@ * cannot check the priority queue, so will only succeed if the last-used provider has * registered a suitable routine. * - * @note There are two interfaces to this framework, epicsGeneralTime.h for consumers + * \note There are two interfaces to this framework, epicsGeneralTime.h for consumers * to obtain a time and query the framework, and generalTimeSup.h for providers * that can supply timestamps. **/ @@ -42,108 +42,108 @@ extern "C" { #endif -/**@def NUM_TIME_EVENTS - * @brief The number of time events that are validated. +/**\def NUM_TIME_EVENTS + * \brief The number of time events that are validated. * * Time Events numbered 0 through (NUM_TIME_EVENTS-1) are validated by code in * epicsGeneralTime.c that tests for advancing timestamps and enforces that * restriction. * - * @note Event numbers greater than or equal to NUM_TIME_EVENTS are now allowed + * \note Event numbers greater than or equal to NUM_TIME_EVENTS are now allowed * if supported by a custom time provider which should provide its own advancing * timestamp validation. **/ #define NUM_TIME_EVENTS 256 -/**@brief Initialise the framework. +/**\brief Initialise the framework. * * This routine is called automatically by any function that requires the * framework. It does not need to be called explicitly. **/ epicsShareFunc void generalTime_Init(void); -/**@brief Install a Time Event time provider that returns the current time for any +/**\brief Install a Time Event time provider that returns the current time for any * Time event number. * - * @note This is optional as it is site policy whether the last resort for a Time + * \note This is optional as it is site policy whether the last resort for a Time * Event time in the absence of any working provider should be a failure, or the * current time. **/ epicsShareFunc int installLastResortEventProvider(void); -/**@brief Reset the internal counter of the number of times the time returned was +/**\brief Reset the internal counter of the number of times the time returned was * earlier than when previously requested. * * Used by device support for binary out record * with: - @code + \code DTYP = "General Time" OUT = "@RSTERRCNT" - @endcode + \endcode **/ epicsShareFunc void generalTimeResetErrorCounts(void); -/**@brief Return the internal counter of the number of times the time returned was +/**\brief Return the internal counter of the number of times the time returned was * earlier than when previously requested. * * Used by device support for longin record * with: - @code + \code DTYP = "General Time" INP = "@GETERRCNT" - @endcode + \endcode * - * @return Reset error counts + * \return Reset error counts **/ epicsShareFunc int generalTimeGetErrorCounts(void); -/**@brief Return the nume of the provider that last returned a valid current time, or +/**\brief Return the nume of the provider that last returned a valid current time, or * NULL if none. * * Used by stringin device support with: - @code + \code DTYP = "General Time" INP = "@BESTTCP" - @endcode + \endcode * - * @return Provider name + * \return Provider name **/ epicsShareFunc const char * generalTimeCurrentProviderName(void); -/**@brief Return the name of the provider that last returned a valid Time Event time, or +/**\brief Return the name of the provider that last returned a valid Time Event time, or * NULL of none. * * Used by stringin device support with: - @code + \code DTYP = "General Time" INP = "@BESTTEP" - @endcode + \endcode * - * @return Provider name + * \return Provider name **/ epicsShareFunc const char * generalTimeEventProviderName(void); -/**@brief Return the name of the registered current time provider that has the highest +/**\brief Return the name of the registered current time provider that has the highest * priority. * * Used by stringin device support with: - @code + \code DTYP = "General Time" INP = "@TOPTCP" - @endcode + \endcode * - * @return Provider name + * \return Provider name **/ epicsShareFunc const char * generalTimeHighestCurrentName(void); -/** @brief Old name provided for backwards compatibility */ +/** \brief Old name provided for backwards compatibility */ #define generalTimeCurrentTpName generalTimeCurrentProviderName -/** @brief Old name provided for backwards compatibility */ +/** \brief Old name provided for backwards compatibility */ #define generalTimeEventTpName generalTimeEventProviderName -/**@brief Provide information about the installed providers and their current best times. +/**\brief Provide information about the installed providers and their current best times. * - * @param interest Desired interest level to report + * \param interest Desired interest level to report **/ epicsShareFunc long generalTimeReport(int interest); diff --git a/modules/libcom/src/osi/epicsMutex.h b/modules/libcom/src/osi/epicsMutex.h index 84d57adc0..89a3410f9 100644 --- a/modules/libcom/src/osi/epicsMutex.h +++ b/modules/libcom/src/osi/epicsMutex.h @@ -7,9 +7,9 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ -/**@file epicsMutex.h +/**\file epicsMutex.h * - * @brief APIs for the epicsMutex mutual exclusion semaphore + * \brief APIs for the epicsMutex mutual exclusion semaphore * * Mutual exclusion semaphores are for situations requiring exclusive access to * resources. An epicsMutex may be claimed recursively, i.e. taken more than @@ -18,16 +18,16 @@ * working on an exclusive resource. * * The typical C++ use of a mutual exclusion semaphore is: - @code + \code epicsMutex *plock = new epicsMutex; ... ... plock->lock(); // process resources plock->unlock(); - @endcode + \endcode * - * @note The implementation: + * \note The implementation: * - MUST implement recursive locking * - SHOULD implement priority inheritance and deletion safety if possible. **/ @@ -38,7 +38,7 @@ #include "shareLib.h" -/**@brief An identifier for an epicsMutex for use with the C API */ +/**\brief An identifier for an epicsMutex for use with the C API */ typedef struct epicsMutexParm *epicsMutexId; /** Return status from some C API routines. */ @@ -53,11 +53,11 @@ typedef enum { #include "compilerDependencies.h" #include "epicsGuard.h" -/**@brief Create a C++ epicsMutex with current filename and line number +/**\brief Create a C++ epicsMutex with current filename and line number */ #define newEpicsMutex new epicsMutex(__FILE__,__LINE__) -/**@brief The C++ API for an epicsMutex. +/**\brief The C++ API for an epicsMutex. */ class epicsShareClass epicsMutex { public: @@ -67,59 +67,59 @@ public: class invalidMutex; /* exception payload */ #if !defined(__GNUC__) || __GNUC__<4 || (__GNUC__==4 && __GNUC_MINOR__<8) - /**@brief Create a mutual exclusion semaphore. + /**\brief Create a mutual exclusion semaphore. **/ epicsMutex (); - /**@brief Create a mutual exclusion semaphore with source location. + /**\brief Create a mutual exclusion semaphore with source location. * - * @note The newEpicsMutex macro simplifies using this constructor. - * @param *pFileName Source file name. - * @param lineno Source line number + * \note The newEpicsMutex macro simplifies using this constructor. + * \param *pFileName Source file name. + * \param lineno Source line number **/ epicsMutex ( const char *pFileName, int lineno ); #else - /**@brief Create a mutual exclusion semaphore. - * @param *pFileName Source file name. - * @param lineno Source line number + /**\brief Create a mutual exclusion semaphore. + * \param *pFileName Source file name. + * \param lineno Source line number **/ epicsMutex ( const char *pFileName = __builtin_FILE(), int lineno = __builtin_LINE() ); #endif - /**@brief Delete the semaphore and its resources. + /**\brief Delete the semaphore and its resources. **/ ~epicsMutex (); - /**@brief Display information about the semaphore. + /**\brief Display information about the semaphore. * - * @note Results are architecture dependant. + * \note Results are architecture dependant. * - * @param level Desired information level to report + * \param level Desired information level to report **/ void show ( unsigned level ) const; - /**@brief Claim the semaphore, waiting until it's free if currently owned + /**\brief Claim the semaphore, waiting until it's free if currently owned * owned by a different thread. * * This call blocks until the calling thread can get exclusive access to * the semaphore. - * @note After a successful lock(), additional recursive locks may be + * \note After a successful lock(), additional recursive locks may be * issued by the same thread, but each must have an associated unlock(). **/ void lock (); - /**@brief Release the semaphore. + /**\brief Release the semaphore. * - * @note If a thread issues recursive locks, it must call unlock() as many + * \note If a thread issues recursive locks, it must call unlock() as many * times as it calls lock(). **/ void unlock (); - /**@brief Similar to lock() except that the call returns immediately if the + /**\brief Similar to lock() except that the call returns immediately if the * semaphore is currently owned by another thread, giving the value false. * - * @return True if the resource is now owned by the caller. - * @return False if some other thread already owns the resource. + * \return True if the resource is now owned by the caller. + * \return False if some other thread already owns the resource. **/ bool tryLock (); private: @@ -128,7 +128,7 @@ private: epicsMutex & operator = ( const epicsMutex & ); }; -/**@brief A semaphore for locating deadlocks in C++ code. */ +/**\brief A semaphore for locating deadlocks in C++ code. */ class epicsShareClass epicsDeadlockDetectMutex { public: typedef epicsGuard guard_t; @@ -154,88 +154,88 @@ private: extern "C" { #endif /*__cplusplus*/ -/**@brief Create an epicsMutex semaphore for use from C code. +/**\brief Create an epicsMutex semaphore for use from C code. * * This macro stores the source location of the creation call in the mutex. - * @return An identifier for the mutex, or NULL if one could not be created. + * \return An identifier for the mutex, or NULL if one could not be created. **/ #define epicsMutexCreate() epicsMutexOsiCreate(__FILE__,__LINE__) -/**@brief Internal API, used by epicsMutexCreate(). */ +/**\brief Internal API, used by epicsMutexCreate(). */ epicsShareFunc epicsMutexId epicsShareAPI epicsMutexOsiCreate( const char *pFileName,int lineno); -/**@brief Create an epicsMutex semaphore for use from C code. +/**\brief Create an epicsMutex semaphore for use from C code. * * This macro stores the source location of the creation call in the mutex. * The routine does not return if the object could not be created. - * @return An identifier for the mutex. + * \return An identifier for the mutex. **/ #define epicsMutexMustCreate() epicsMutexOsiMustCreate(__FILE__,__LINE__) -/**@brief Internal API, used by epicsMutexMustCreate(). */ +/**\brief Internal API, used by epicsMutexMustCreate(). */ epicsShareFunc epicsMutexId epicsShareAPI epicsMutexOsiMustCreate( const char *pFileName,int lineno); -/**@brief Destroy an epicsMutex semaphore. - * @param id The mutex identifier. +/**\brief Destroy an epicsMutex semaphore. + * \param id The mutex identifier. **/ epicsShareFunc void epicsShareAPI epicsMutexDestroy(epicsMutexId id); -/**@brief Release the semaphore. - * @param id The mutex identifier. - * @note If a thread issues recursive locks, it must call epicsMutexUnlock() +/**\brief Release the semaphore. + * \param id The mutex identifier. + * \note If a thread issues recursive locks, it must call epicsMutexUnlock() * as many times as it calls epicsMutexLock() or equivalents. **/ epicsShareFunc void epicsShareAPI epicsMutexUnlock(epicsMutexId id); -/**@brief Claim the semaphore, waiting until it's free if currently owned +/**\brief Claim the semaphore, waiting until it's free if currently owned * owned by a different thread. * * This call blocks until the calling thread can get exclusive access to * the semaphore. - * @note After a successful lock(), additional recursive locks may be + * \note After a successful lock(), additional recursive locks may be * issued by the same thread, but each must have an associated unlock(). - * @param id The mutex identifier. - * @return Status indicator. + * \param id The mutex identifier. + * \return Status indicator. **/ epicsShareFunc epicsMutexLockStatus epicsShareAPI epicsMutexLock( epicsMutexId id); -/**@brief Claim a semaphore (see epicsMutexLock()). +/**\brief Claim a semaphore (see epicsMutexLock()). * * This routine does not return if the identifier is invalid. - * @param ID The mutex identifier. + * \param ID The mutex identifier. **/ #define epicsMutexMustLock(ID) { \ epicsMutexLockStatus status = epicsMutexLock(ID); \ assert(status == epicsMutexLockOK); \ } -/**@brief Similar to epicsMutexLock() except that the call returns immediately, +/**\brief Similar to epicsMutexLock() except that the call returns immediately, * with the return status indicating if the semaphore is currently owned by * this thread or another thread. * - * @return \c epicsMutexLockOK if the resource is now owned by the caller. - * @return \c epicsMutexLockTimeout if some other thread owns the resource. + * \return \c epicsMutexLockOK if the resource is now owned by the caller. + * \return \c epicsMutexLockTimeout if some other thread owns the resource. **/ epicsShareFunc epicsMutexLockStatus epicsShareAPI epicsMutexTryLock( epicsMutexId id); -/**@brief Display information about the semaphore. +/**\brief Display information about the semaphore. * - * @note Results are architecture dependant. + * \note Results are architecture dependant. * - * @param id The mutex identifier. - * @param level Desired information level to report + * \param id The mutex identifier. + * \param level Desired information level to report **/ epicsShareFunc void epicsShareAPI epicsMutexShow( epicsMutexId id,unsigned int level); -/**@brief Display information about all epicsMutex semaphores. +/**\brief Display information about all epicsMutex semaphores. * - * @note Results are architecture dependant. + * \note Results are architecture dependant. * - * @param onlyLocked Non-zero to show only locked semaphores. - * @param level Desired information level to report + * \param onlyLocked Non-zero to show only locked semaphores. + * \param level Desired information level to report **/ epicsShareFunc void epicsShareAPI epicsMutexShowAll( int onlyLocked,unsigned int level); diff --git a/modules/libcom/src/osi/epicsReadline.h b/modules/libcom/src/osi/epicsReadline.h index ab3faa160..78c233119 100644 --- a/modules/libcom/src/osi/epicsReadline.h +++ b/modules/libcom/src/osi/epicsReadline.h @@ -8,9 +8,9 @@ \*************************************************************************/ /** - * @file epicsReadline.h - * @brief Command-line editing functions - * @author Eric Norum + * \file epicsReadline.h + * \brief Command-line editing functions + * \author Eric Norum * * Provides a generalized API for command line history and line-editing. * The implementation of this API can call GNU Readline, libtecla, and on @@ -26,21 +26,21 @@ extern "C" { #include #include /** - * @brief Create a command-line context - * @param in Filehandle to read from - * @returns Command-line context + * \brief Create a command-line context + * \param in Filehandle to read from + * \return Command-line context */ epicsShareFunc void * epicsShareAPI epicsReadlineBegin (FILE *in); /** - * @brief Read a line of input - * @param prompt Prompt string - * @param context To read from - * @returns Line read + * \brief Read a line of input + * \param prompt Prompt string + * \param context To read from + * \return Line read */ epicsShareFunc char * epicsShareAPI epicsReadline (const char *prompt, void *context); /** - * @brief Destroy a command-line context - * @param context Command-line context to destroy + * \brief Destroy a command-line context + * \param context Command-line context to destroy */ epicsShareFunc void epicsShareAPI epicsReadlineEnd (void *context); diff --git a/modules/libcom/src/osi/epicsThread.h b/modules/libcom/src/osi/epicsThread.h index b154e83e6..b25c3cd7c 100644 --- a/modules/libcom/src/osi/epicsThread.h +++ b/modules/libcom/src/osi/epicsThread.h @@ -65,6 +65,9 @@ extern "C" { typedef void (*EPICSTHREADFUNC)(void *parm); +/** @name Some Named Thread Priorities + * @{ + */ #define epicsThreadPriorityMax 99 #define epicsThreadPriorityMin 0 @@ -80,6 +83,7 @@ typedef void (*EPICSTHREADFUNC)(void *parm); #define epicsThreadPriorityScanHigh 70 #define epicsThreadPriorityIocsh 91 #define epicsThreadPriorityBaseMax 91 +/** @} */ /** Stack sizes for each stackSizeClass are implementation and CPU dependent. */ typedef enum { @@ -114,13 +118,13 @@ typedef epicsThreadId epicsThreadOnceId; * -# myInitFunc will have returned before any other epicsThreadOnce * call using the same epicsThreadOnceId returns. * - * @code + * \code * static epicsThreadOnceId onceId = EPICS_THREAD_ONCE_INIT; * static void myInitFunc(void *arg) { ... } * static void some Function(void) { * epicsThreadOnce(&onceId, &myInitFunc, NULL); * } - * @endcode + * \endcode */ epicsShareFunc void epicsShareAPI epicsThreadOnce( epicsThreadOnceId *id, EPICSTHREADFUNC, void *arg); @@ -163,12 +167,12 @@ typedef struct epicsThreadOpts { #define EPICS_THREAD_OPTS_INIT { \ epicsThreadPriorityLow, epicsThreadStackMedium, 0} -/** @brief Allocate and start a new OS thread. - * @param name A name describing this thread. Appears in various log and error message. - * @param funptr The thread main function. - * @param parm Passed to thread main function. - * @param opts Modifiers for the new thread, or NULL to use target specific defaults. - * @return NULL on error +/** \brief Allocate and start a new OS thread. + * \param name A name describing this thread. Appears in various log and error message. + * \param funptr The thread main function. + * \param parm Passed to thread main function. + * \param opts Modifiers for the new thread, or NULL to use target specific defaults. + * \return NULL on error */ epicsShareFunc epicsThreadId epicsThreadCreateOpt ( const char * name, @@ -222,14 +226,14 @@ epicsShareFunc int epicsShareAPI epicsThreadIsEqual( * for other reasons. **/ epicsShareFunc int epicsShareAPI epicsThreadIsSuspended(epicsThreadId id); -/** @brief Block the calling thread for at least the specified time. - * @param seconds Time to wait in seconds. Values <=0 blocks for the shortest possible time. +/** \brief Block the calling thread for at least the specified time. + * \param seconds Time to wait in seconds. Values <=0 blocks for the shortest possible time. */ epicsShareFunc void epicsShareAPI epicsThreadSleep(double seconds); -/** @brief Query a value approximating the OS timer/scheduler resolution. - * @return A value in seconds >=0 +/** \brief Query a value approximating the OS timer/scheduler resolution. + * \return A value in seconds >=0 * - * @warning On targets other than vxWorks and RTEMS, the quantum value often isn't + * \warning On targets other than vxWorks and RTEMS, the quantum value often isn't * meaningful. Use of this function is discouraged in portable code. */ epicsShareFunc double epicsShareAPI epicsThreadSleepQuantum(void); @@ -238,23 +242,23 @@ epicsShareFunc double epicsShareAPI epicsThreadSleepQuantum(void); */ epicsShareFunc epicsThreadId epicsShareAPI epicsThreadGetIdSelf(void); /** Attempt to find the first instance of a thread by name. - * @return An epicsThreadId, or NULL if no such thread is currently running. + * \return An epicsThreadId, or NULL if no such thread is currently running. * Note that a non-NULL ID may still be invalid if this call races * with thread exit. * - * @warning Safe use of this function requires external knowledge that this + * \warning Safe use of this function requires external knowledge that this * thread will not return. */ epicsShareFunc epicsThreadId epicsShareAPI epicsThreadGetId(const char *name); /** Return a value approximating the number of threads which this target * can run in parallel. This value is advisory. - * @return >=1 + * \return >=1 */ epicsShareFunc int epicsThreadGetCPUs(void); /** Return the name of the current thread. * - * @return Never NULL. Storage lifetime tied to epicsThreadId. + * \return Never NULL. Storage lifetime tied to epicsThreadId. * * This is either a copy of the string passed to epicsThread*Create*(), * or an arbitrary unique string for non-EPICS threads. @@ -285,7 +289,7 @@ epicsShareFunc int epicsShareAPI epicsThreadIsOkToBlock(void); epicsShareFunc void epicsShareAPI epicsThreadSetOkToBlock(int isOkToBlock); /** Print to stdout information about all running EPICS threads. - * @param level 0 prints minimal output. Higher values print more details. + * \param level 0 prints minimal output. Higher values print more details. */ epicsShareFunc void epicsShareAPI epicsThreadShowAll(unsigned int level); /** Print info about a single EPICS thread. */ @@ -356,18 +360,18 @@ public: extern "C" void epicsThreadCallEntryPoint ( void * ); -/** @brief An OS thread +/** \brief An OS thread * * A wrapper around the epicsThread* C API. * - * @note Threads must be start() ed. + * \note Threads must be start() ed. */ class epicsShareClass epicsThread { public: /** Create a new thread with the provided information. * * cf. epicsThreadOpts - * @note Threads must be start() ed. + * \note Threads must be start() ed. * @throws epicsThread::unableToCreateThread on error. */ epicsThread ( epicsThreadRunable &,const char *name, unsigned int stackSize, @@ -378,11 +382,11 @@ public: //! Wait for the thread epicsRunnable::run() to return. void exitWait () throw (); //! Wait for the thread epicsRunnable::run() to return. - //! @param delay Wait up to this many seconds. - //! @returns true if run() returned. false on timeout. + //! \param delay Wait up to this many seconds. + //! \return true if run() returned. false on timeout. bool exitWait ( const double delay ) throw (); //! @throws A special exitException which will be caught and ignored. - //! @note This exitException doesn't not derive from std::exception + //! \note This exitException doesn't not derive from std::exception static void exit (); //! cf. epicsThreadResume() void resume () throw (); @@ -396,7 +400,7 @@ public: void setPriority ( unsigned int ) throw (); bool priorityIsEqual ( const epicsThread & ) const throw (); bool isSuspended () const throw (); - //! @return true if call through this thread's epicsRunnable::run() + //! \return true if call through this thread's epicsRunnable::run() bool isCurrentThread () const throw (); bool operator == ( const epicsThread & ) const throw (); //! Say something interesting about this thread to stdout. diff --git a/modules/libcom/src/osi/os/WIN32/osiFileName.h b/modules/libcom/src/osi/os/WIN32/osiFileName.h index ced745f71..bba2d55c1 100644 --- a/modules/libcom/src/osi/os/WIN32/osiFileName.h +++ b/modules/libcom/src/osi/os/WIN32/osiFileName.h @@ -25,13 +25,13 @@ extern "C" { #define OSI_PATH_SEPARATOR "\\" /** Return the absolute path of the current executable. - @returns NULL or the path. Caller must free() + * \return NULL or the path. Caller must free() */ epicsShareFunc char *epicsGetExecName(void); /** Return the absolute path of the directory containing the current executable. - @returns NULL or the path. Caller must free() + * \return NULL or the path. Caller must free() */ epicsShareFunc char *epicsGetExecDir(void); diff --git a/modules/libcom/src/osi/os/cygwin32/osiFileName.h b/modules/libcom/src/osi/os/cygwin32/osiFileName.h index 1e7799098..76562f3e4 100644 --- a/modules/libcom/src/osi/os/cygwin32/osiFileName.h +++ b/modules/libcom/src/osi/os/cygwin32/osiFileName.h @@ -24,13 +24,13 @@ extern "C" { #define OSI_PATH_SEPARATOR "\\" /** Return the absolute path of the current executable. - @returns NULL or the path. Caller must free() + \return NULL or the path. Caller must free() */ epicsShareFunc char *epicsGetExecName(void); /** Return the absolute path of the directory containing the current executable. - @returns NULL or the path. Caller must free() + \return NULL or the path. Caller must free() */ epicsShareFunc char *epicsGetExecDir(void); diff --git a/modules/libcom/src/osi/os/default/epicsMMIODef.h b/modules/libcom/src/osi/os/default/epicsMMIODef.h index 04890bb5a..114a67c6e 100644 --- a/modules/libcom/src/osi/os/default/epicsMMIODef.h +++ b/modules/libcom/src/osi/os/default/epicsMMIODef.h @@ -5,12 +5,12 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file epicsMMIODef.h - * @brief Memory Mapped I/O + * \file epicsMMIODef.h + * \brief Memory Mapped I/O * * Definitions related to Memory Mapped I/O * - * @author Michael Davidsaver + * \author Michael Davidsaver * @ingroup mmio */ @@ -32,7 +32,7 @@ *@{ */ -/** @brief Read a single byte. +/** \brief Read a single byte. */ static EPICS_ALWAYS_INLINE epicsUInt8 @@ -41,7 +41,7 @@ ioread8(volatile void* addr) return *(volatile epicsUInt8*)(addr); } -/** @brief Write a single byte. +/** \brief Write a single byte. */ static EPICS_ALWAYS_INLINE void @@ -50,7 +50,7 @@ iowrite8(volatile void* addr, epicsUInt8 val) *(volatile epicsUInt8*)(addr) = val; } -/** @brief Read two bytes in host order. +/** \brief Read two bytes in host order. * Not byte swapping */ static EPICS_ALWAYS_INLINE @@ -60,7 +60,7 @@ nat_ioread16(volatile void* addr) return *(volatile epicsUInt16*)(addr); } -/** @brief Write two byte in host order. +/** \brief Write two byte in host order. * Not byte swapping */ static EPICS_ALWAYS_INLINE @@ -70,7 +70,7 @@ nat_iowrite16(volatile void* addr, epicsUInt16 val) *(volatile epicsUInt16*)(addr) = val; } -/** @brief Read four bytes in host order. +/** \brief Read four bytes in host order. * Not byte swapping */ static EPICS_ALWAYS_INLINE @@ -80,7 +80,7 @@ nat_ioread32(volatile void* addr) return *(volatile epicsUInt32*)(addr); } -/** @brief Write four byte in host order. +/** \brief Write four byte in host order. * Not byte swapping */ static EPICS_ALWAYS_INLINE @@ -157,50 +157,50 @@ bswap32(epicsUInt32 value) # error Unable to determine native byte order #endif -/** @def bswap16 - * @brief Unconditional two byte swap +/** \def bswap16 + * \brief Unconditional two byte swap */ -/** @def bswap32 - * @brief Unconditional four byte swap +/** \def bswap32 + * \brief Unconditional four byte swap */ -/** @def be_ioread16 - * @brief Read two byte in big endian order. +/** \def be_ioread16 + * \brief Read two byte in big endian order. */ -/** @def be_iowrite16 - * @brief Write two byte in big endian order. +/** \def be_iowrite16 + * \brief Write two byte in big endian order. */ -/** @def be_ioread32 - * @brief Read four byte in big endian order. +/** \def be_ioread32 + * \brief Read four byte in big endian order. */ -/** @def be_iowrite32 - * @brief Write four byte in big endian order. +/** \def be_iowrite32 + * \brief Write four byte in big endian order. */ -/** @def le_ioread16 - * @brief Read two byte in little endian order. +/** \def le_ioread16 + * \brief Read two byte in little endian order. */ -/** @def le_iowrite16 - * @brief Write two byte in little endian order. +/** \def le_iowrite16 + * \brief Write two byte in little endian order. */ -/** @def le_ioread32 - * @brief Read four byte in little endian order. +/** \def le_ioread32 + * \brief Read four byte in little endian order. */ -/** @def le_iowrite32 - * @brief Write four byte in little endian order. +/** \def le_iowrite32 + * \brief Write four byte in little endian order. */ /** @ingroup mmio *@{ */ -/** @brief Explicit read memory barrier +/** \brief Explicit read memory barrier * Prevents reordering of reads around it. */ #define rbarr() do{}while(0) -/** @brief Explicit write memory barrier +/** \brief Explicit write memory barrier * Prevents reordering of writes around it. */ #define wbarr() do{}while(0) -/** @brief Explicit read/write memory barrier +/** \brief Explicit read/write memory barrier * Prevents reordering of reads or writes around it. */ #define rwbarr() do{}while(0) @@ -239,30 +239,30 @@ bswap32(epicsUInt32 value) * *@b PCI * - @code + \code be_iowrite16(base+off, 14); var = be_ioread16(base+off); - @endcode + \endcode * *@b VME * - @code + \code nat_iowrite16(base+off, 14); var = nat_ioread16(base+off); - @endcode + \endcode * *@subsection mmioexle Little endian device * *@b PCI - @code + \code le_iowrite16(base+off, 14); var = le_ioread16(base+off); - @endcode + \endcode *@b VME - @code + \code nat_iowrite16(base+off, bswap16(14)); var = bswap16(nat_iowrite16(base+off)); - @endcode + \endcode *This difference arises because VME bridges implement hardware byte *swapping on little endian systems, while PCI bridges do not. *Software accessing PCI devices must know if byte swapping is required. @@ -274,7 +274,7 @@ bswap32(epicsUInt32 value) * *Software accessing VME must @b not do conditional swapping. * - *@note All read and write operations have an implicit read or write barrier. + *\note All read and write operations have an implicit read or write barrier. */ /** @} */ diff --git a/modules/libcom/src/osi/osiPoolStatus.h b/modules/libcom/src/osi/osiPoolStatus.h index 45bc1eaf9..197d5fc96 100644 --- a/modules/libcom/src/osi/osiPoolStatus.h +++ b/modules/libcom/src/osi/osiPoolStatus.h @@ -7,9 +7,9 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ -/**@file osiPoolStatus.h - * @author Jeff Hill - * @brief Functions to check the state of the system memory pool. +/**\file osiPoolStatus.h + * \author Jeff Hill + * \brief Functions to check the state of the system memory pool. * **/ @@ -23,17 +23,17 @@ extern "C" { #endif -/**@brief Checks if a memory block of a specific size can be safely allocated. +/**\brief Checks if a memory block of a specific size can be safely allocated. * * The meaning of "safely allocated" is target-specific, some additional free * space is usually necessary to keep the system running reliably. * On vxWorks this returns True if at least 100000 bytes is free. * - * @note This routine is called quite frequently by the IOC so an efficent + * \note This routine is called quite frequently by the IOC so an efficent * implementation is important. * - * @param contiguousBlockSize Block size to check. - * @return True if the requested memory should be available. + * \param contiguousBlockSize Block size to check. + * \return True if the requested memory should be available. */ epicsShareFunc int epicsShareAPI osiSufficentSpaceInPool ( size_t contiguousBlockSize ); diff --git a/modules/libcom/src/ring/epicsRingBytes.h b/modules/libcom/src/ring/epicsRingBytes.h index ef51ba577..870d44093 100644 --- a/modules/libcom/src/ring/epicsRingBytes.h +++ b/modules/libcom/src/ring/epicsRingBytes.h @@ -8,18 +8,18 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file epicsRingBytes.h - * @author Marty Kraimer, Eric Norum, Ralph Lange - * @brief A circular buffer to store bytes + * \file epicsRingBytes.h + * \author Marty Kraimer, Eric Norum, Ralph Lange + * \brief A circular buffer to store bytes * - * @details + * \details * EpicsRingBytes provides a C API for creating and using ring buffers * (first in first out circular buffers) that store bytes. The unlocked * variant is designed so that one writer thread and one reader thread * can access the ring simultaneously without requiring mutual exclusion. * The locked variant uses an epicsSpinLock, and works with any numbers of * writer and reader threads. - * @note If there is only one writer it is not necessary to lock for puts. + * \note If there is only one writer it is not necessary to lock for puts. * If there is a single reader it is not necessary to lock for gets. * epicsRingBytesLocked uses a spinlock. */ @@ -33,97 +33,97 @@ extern "C" { #include "shareLib.h" -/** @brief An identifier for a ring buffer */ +/** \brief An identifier for a ring buffer */ typedef void *epicsRingBytesId; typedef void const *epicsRingBytesIdConst; /** - * @brief Create a new ring buffer - * @param nbytes Size of ring buffer to create - * @return Ring buffer Id or NULL on failure + * \brief Create a new ring buffer + * \param nbytes Size of ring buffer to create + * \return Ring buffer Id or NULL on failure */ epicsShareFunc epicsRingBytesId epicsShareAPI epicsRingBytesCreate(int nbytes); /** - * @brief Create a new ring buffer, secured by a spinlock - * @param nbytes Size of ring buffer to create - * @return Ring buffer Id or NULL on failure + * \brief Create a new ring buffer, secured by a spinlock + * \param nbytes Size of ring buffer to create + * \return Ring buffer Id or NULL on failure */ epicsShareFunc epicsRingBytesId epicsShareAPI epicsRingBytesLockedCreate(int nbytes); /** - * @brief Delete the ring buffer and free any associated memory - * @param id RingbufferID returned by epicsRingBytesCreate() + * \brief Delete the ring buffer and free any associated memory + * \param id RingbufferID returned by epicsRingBytesCreate() */ epicsShareFunc void epicsShareAPI epicsRingBytesDelete(epicsRingBytesId id); /** - * @brief Read data out of the ring buffer - * @param id RingbufferID returned by epicsRingBytesCreate() - * @param value Where to put the data fetched from the buffer - * @param nbytes Maximum number of bytes to get - * @return The number of bytes actually fetched + * \brief Read data out of the ring buffer + * \param id RingbufferID returned by epicsRingBytesCreate() + * \param value Where to put the data fetched from the buffer + * \param nbytes Maximum number of bytes to get + * \return The number of bytes actually fetched */ epicsShareFunc int epicsShareAPI epicsRingBytesGet( epicsRingBytesId id, char *value,int nbytes); /** - * @brief Write data into the ring buffer - * @param id RingbufferID returned by epicsRingBytesCreate() - * @param value Source of the data to be put into the buffer - * @param nbytes How many bytes to put - * @return The number of bytes actually stored, zero if not enough space + * \brief Write data into the ring buffer + * \param id RingbufferID returned by epicsRingBytesCreate() + * \param value Source of the data to be put into the buffer + * \param nbytes How many bytes to put + * \return The number of bytes actually stored, zero if not enough space */ epicsShareFunc int epicsShareAPI epicsRingBytesPut( epicsRingBytesId id, char *value,int nbytes); /** - * @brief Make the ring buffer empty - * @param id RingbufferID returned by epicsRingBytesCreate() - * @note Should only be used when both gets and puts are locked out. + * \brief Make the ring buffer empty + * \param id RingbufferID returned by epicsRingBytesCreate() + * \note Should only be used when both gets and puts are locked out. */ epicsShareFunc void epicsShareAPI epicsRingBytesFlush(epicsRingBytesId id); /** - * @brief Return the number of free bytes in the ring buffer - * @param id RingbufferID returned by epicsRingBytesCreate() - * @return The number of free bytes in the ring buffer + * \brief Return the number of free bytes in the ring buffer + * \param id RingbufferID returned by epicsRingBytesCreate() + * \return The number of free bytes in the ring buffer */ epicsShareFunc int epicsShareAPI epicsRingBytesFreeBytes(epicsRingBytesId id); /** - * @brief Return the number of bytes currently stored in the ring buffer - * @param id RingbufferID returned by epicsRingBytesCreate() - * @return The number of bytes currently stored in the ring buffer + * \brief Return the number of bytes currently stored in the ring buffer + * \param id RingbufferID returned by epicsRingBytesCreate() + * \return The number of bytes currently stored in the ring buffer */ epicsShareFunc int epicsShareAPI epicsRingBytesUsedBytes(epicsRingBytesId id); /** - * @brief Return the size of the ring buffer - * @param id RingbufferID returned by epicsRingBytesCreate() - * @return Return the size of the ring buffer, i.e., nbytes specified in + * \brief Return the size of the ring buffer + * \param id RingbufferID returned by epicsRingBytesCreate() + * \return Return the size of the ring buffer, i.e., nbytes specified in * the call to epicsRingBytesCreate(). */ epicsShareFunc int epicsShareAPI epicsRingBytesSize(epicsRingBytesId id); /** - * @brief Test if the ring buffer is currently empty. - * @param id RingbufferID returned by epicsRingBytesCreate() - * @return 1 if the buffer is empty, otherwise 0 + * \brief Test if the ring buffer is currently empty. + * \param id RingbufferID returned by epicsRingBytesCreate() + * \return 1 if the buffer is empty, otherwise 0 */ epicsShareFunc int epicsShareAPI epicsRingBytesIsEmpty(epicsRingBytesId id); /** - * @brief Test if the ring buffer is currently full. - * @param id RingbufferID returned by epicsRingBytesCreate() - * @return 1 if the buffer is full, otherwise 0 + * \brief Test if the ring buffer is currently full. + * \param id RingbufferID returned by epicsRingBytesCreate() + * \return 1 if the buffer is full, otherwise 0 */ epicsShareFunc int epicsShareAPI epicsRingBytesIsFull(epicsRingBytesId id); /** - * @brief See how full a ring buffer has been since it was last checked. + * \brief See how full a ring buffer has been since it was last checked. * * Returns the maximum amount of data the ring buffer has held in bytes * since the water mark was last reset. A new ring buffer starts with a * water mark of 0. - * @param id RingbufferID returned by epicsRingBytesCreate() - * @return Actual Highwater mark + * \param id RingbufferID returned by epicsRingBytesCreate() + * \return Actual Highwater mark */ epicsShareFunc int epicsShareAPI epicsRingBytesHighWaterMark(epicsRingBytesIdConst id); /** - * @brief Reset the Highwater mark of the ring buffer. + * \brief Reset the Highwater mark of the ring buffer. * * The Highwater mark will be set to the current usage - * @param id RingbufferID returned by epicsRingBytesCreate() + * \param id RingbufferID returned by epicsRingBytesCreate() */ epicsShareFunc void epicsShareAPI epicsRingBytesResetHighWaterMark(epicsRingBytesId id); diff --git a/modules/libcom/src/ring/epicsRingPointer.h b/modules/libcom/src/ring/epicsRingPointer.h index c50128247..8ecdcec81 100644 --- a/modules/libcom/src/ring/epicsRingPointer.h +++ b/modules/libcom/src/ring/epicsRingPointer.h @@ -8,18 +8,18 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ /** - * @file epicsRingPointer.h - * @brief A circular buffer to store pointers - * @author Marty Kraimer, Ralph Lange + * \file epicsRingPointer.h + * \brief A circular buffer to store pointers + * \author Marty Kraimer, Ralph Lange * - * @details + * \details * epicsRingPointer.h provides both C and C++ APIs for creating and using ring * buffers (first in first out circular buffers) that store pointers. The * unlocked kind is designed so that one writer thread and one reader thread * can access the ring simultaneously without requiring mutual exclusion. The * locked variant uses an epicsSpinLock, and works with any numbers of writer * and reader threads. - * @note If there is only one writer it is not necessary to lock pushes. + * \note If there is only one writer it is not necessary to lock pushes. * If there is a single reader it is not necessary to lock pops. * epicsRingPointerLocked uses a spinlock. */ @@ -33,63 +33,63 @@ #ifdef __cplusplus /** - * @brief A C++ template class providing methods for creating and using a ring + * \brief A C++ template class providing methods for creating and using a ring * buffer (a first in, first out circular buffer) that stores pointers to * objects of the template type. */ template class epicsRingPointer { public: /* Functions */ - /**@brief Constructor - * @param size Maximum number of elements (pointers) that can be stored - * @param locked If true, the spin lock secured variant is created + /**\brief Constructor + * \param size Maximum number of elements (pointers) that can be stored + * \param locked If true, the spin lock secured variant is created */ epicsRingPointer(int size, bool locked); - /**@brief Destructor + /**\brief Destructor */ ~epicsRingPointer(); - /**@brief Push a new entry on the ring - * @return True on success, False if the buffer was full + /**\brief Push a new entry on the ring + * \return True on success, False if the buffer was full */ bool push(T *p); - /**@brief Take an element off the ring - * @return The element, or NULL if the ring was empty + /**\brief Take an element off the ring + * \return The element, or NULL if the ring was empty */ T* pop(); - /**@brief Remove all elements from the ring. - * @note If this operation is performed on a ring buffer of the + /**\brief Remove all elements from the ring. + * \note If this operation is performed on a ring buffer of the * unsecured kind, all access to the ring should be locked. */ void flush(); - /**@brief Get how much free space remains in the ring - * @return The number of additional elements the ring could hold. + /**\brief Get how much free space remains in the ring + * \return The number of additional elements the ring could hold. */ int getFree() const; - /**@brief Get how many elements are stored on the ring - * @return The number of elements currently stored. + /**\brief Get how many elements are stored on the ring + * \return The number of elements currently stored. */ int getUsed() const; - /**@brief Get the size of the ring - * @return The @c size specified when the ring was created. + /**\brief Get the size of the ring + * \return The \c size specified when the ring was created. */ int getSize() const; - /**@brief Test if the ring is currently empty - * @return True if the ring is empty, otherwise false. + /**\brief Test if the ring is currently empty + * \return True if the ring is empty, otherwise false. */ bool isEmpty() const; - /**@brief Test if the ring is currently full - * @return True if the ring is full, otherwise false. + /**\brief Test if the ring is currently full + * \return True if the ring is full, otherwise false. */ bool isFull() const; - /**@brief See how full the ring has got since it was last checked. + /**\brief See how full the ring has got since it was last checked. * * Returns the maximum number of elements the ring * buffer has held since the water mark was last reset. * A new ring buffer starts with a water mark of 0. - * @return Actual highwater mark + * \return Actual highwater mark */ int getHighWaterMark() const; - /**@brief Reset high water mark + /**\brief Reset high water mark * * High water mark will be set to the current usage */ @@ -114,92 +114,92 @@ private: /* Data */ extern "C" { #endif /*__cplusplus */ -/** @brief An identifier for the C API to a ring buffer storing pointers */ +/** \brief An identifier for the C API to a ring buffer storing pointers */ typedef void *epicsRingPointerId; typedef void const *epicsRingPointerIdConst; /** - * @brief Create a new ring buffer - * @param size Size of ring buffer to create - * @return Ring buffer identifier or NULL on failure + * \brief Create a new ring buffer + * \param size Size of ring buffer to create + * \return Ring buffer identifier or NULL on failure */ epicsShareFunc epicsRingPointerId epicsShareAPI epicsRingPointerCreate(int size); /** - * @brief Create a new ring buffer, secured by a spinlock - * @param size Size of ring buffer to create - * @return Ring buffer identifier or NULL on failure + * \brief Create a new ring buffer, secured by a spinlock + * \param size Size of ring buffer to create + * \return Ring buffer identifier or NULL on failure */ epicsShareFunc epicsRingPointerId epicsShareAPI epicsRingPointerLockedCreate(int size); /** - * @brief Delete the ring buffer and free any associated memory - * @param id Ring buffer identifier + * \brief Delete the ring buffer and free any associated memory + * \param id Ring buffer identifier */ epicsShareFunc void epicsShareAPI epicsRingPointerDelete(epicsRingPointerId id); /** - * @brief Push pointer into the ring buffer - * @param id Ring buffer identifier - * @param p Pointer to be pushed to the ring - * @return 1 if the pointer was successfully pushed, 0 if the buffer was full + * \brief Push pointer into the ring buffer + * \param id Ring buffer identifier + * \param p Pointer to be pushed to the ring + * \return 1 if the pointer was successfully pushed, 0 if the buffer was full */ epicsShareFunc int epicsShareAPI epicsRingPointerPush(epicsRingPointerId id,void *p); /** - * @brief Take an element off the ring - * @param id Ring buffer identifier - * @return The pointer from the buffer, or NULL if the ring was empty + * \brief Take an element off the ring + * \param id Ring buffer identifier + * \return The pointer from the buffer, or NULL if the ring was empty */ epicsShareFunc void* epicsShareAPI epicsRingPointerPop(epicsRingPointerId id) ; /** - * @brief Remove all elements from the ring - * @param id Ring buffer identifier - * @note If this operation is performed on a ring buffer of the unsecured + * \brief Remove all elements from the ring + * \param id Ring buffer identifier + * \note If this operation is performed on a ring buffer of the unsecured * kind, all access to the ring should be locked. */ epicsShareFunc void epicsShareAPI epicsRingPointerFlush(epicsRingPointerId id); /** - * @brief Return the amount of empty space in the ring buffer - * @param id Ring buffer identifier - * @return The number of additional elements it could hold. + * \brief Return the amount of empty space in the ring buffer + * \param id Ring buffer identifier + * \return The number of additional elements it could hold. */ epicsShareFunc int epicsShareAPI epicsRingPointerGetFree(epicsRingPointerId id); /** - * @brief Return the number of elements stored in the ring buffer - * @param id Ring buffer identifier - * @return The number of elements stored in the ring buffer + * \brief Return the number of elements stored in the ring buffer + * \param id Ring buffer identifier + * \return The number of elements stored in the ring buffer */ epicsShareFunc int epicsShareAPI epicsRingPointerGetUsed(epicsRingPointerId id); /** - * @brief Return the size of the ring - * @param id Ring buffer identifier - * @return The size of the ring buffer, i.e. the value of @c size + * \brief Return the size of the ring + * \param id Ring buffer identifier + * \return The size of the ring buffer, i.e. the value of \c size * given when the ring was created. */ epicsShareFunc int epicsShareAPI epicsRingPointerGetSize(epicsRingPointerId id); /** - * @brief Check if the ring buffer is currently empty - * @param id Ring buffer identifier - * @return 1 if the ring is empty, otherwise 0 + * \brief Check if the ring buffer is currently empty + * \param id Ring buffer identifier + * \return 1 if the ring is empty, otherwise 0 */ epicsShareFunc int epicsShareAPI epicsRingPointerIsEmpty(epicsRingPointerId id); /** - * @brief Check if the ring buffer is currently full - * @param id Ring buffer identifier - * @return 1 if the ring buffer is full, otherwise 0 + * \brief Check if the ring buffer is currently full + * \param id Ring buffer identifier + * \return 1 if the ring buffer is full, otherwise 0 */ epicsShareFunc int epicsShareAPI epicsRingPointerIsFull(epicsRingPointerId id); /** - * @brief Get the Highwater mark of the ring buffer + * \brief Get the Highwater mark of the ring buffer * * Returns the largest number of elements the ring buffer has held since * the water mark was last reset. A new ring buffer starts with a * water mark of 0. - * @param id Ring buffer identifier - * @return Actual Highwater mark + * \param id Ring buffer identifier + * \return Actual Highwater mark */ epicsShareFunc int epicsShareAPI epicsRingPointerGetHighWaterMark(epicsRingPointerIdConst id); /** - * @brief Reset the Highwater mark of the ring buffer + * \brief Reset the Highwater mark of the ring buffer * * The Highwater mark will be set to the current usage - * @param id Ring buffer identifier + * \param id Ring buffer identifier */ epicsShareFunc void epicsShareAPI epicsRingPointerResetHighWaterMark(epicsRingPointerId id);