Misc doxygen fixes and updates

This commit is contained in:
Andrew Johnson
2021-09-25 22:34:05 -05:00
parent 3d09106b51
commit 7d2ca62a78
5 changed files with 68 additions and 59 deletions

View File

@ -2300,7 +2300,7 @@ PLANTUML_JAR_PATH =
# Minimum value: 0, maximum value: 10000, default value: 50.
# This tag requires that the tag HAVE_DOT is set to YES.
DOT_GRAPH_MAX_NODES = 50
DOT_GRAPH_MAX_NODES = 100
# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
# generated by dot. A depth value of 3 means that only nodes reachable from the

View File

@ -99,7 +99,7 @@ DBCORE_API void testdbVGetFieldEqual(const char* pv, short dbrType, va_list ap);
/** Assert that a dbPutField() array operation will complete successfully.
*
* @param pv a PV name, possibly including filter expression
* @param a DBF_\* type code (cf. dbfType in dbFldTypes.h)
* @param dbrType a DBF_\* type code (cf. dbfType in dbFldTypes.h)
* @param count Number of elements in pbuf array
* @param pbuf Array of values to write
*
@ -114,7 +114,7 @@ DBCORE_API void testdbPutArrFieldOk(const char* pv, short dbrType, unsigned long
/**
* @param pv PV name string
* @param dbfType One of the DBF_* macros from dbAccess.h
* @param dbfType One of the DBF_\* macros from dbAccess.h
* @param nRequest Number of elements to request from pv
* @param pbufcnt Number of elements pointed to be pbuf
* @param pbuf Expected value buffer

View File

@ -15,14 +15,14 @@
* \brief Functions for interacting with the errlog task
*
* This file contains functions for passing error messages with varying severity,
* registering and un-registering listeners and modifying the log buffer size and
* registering and un-registering listeners and modifying the log buffer size and
* max message size.
*
* Some of these functions are similar to the standard C library functions printf
* and vprintf. For details on the arguments and return codes it is useful to consult
* any book that describes the standard C library such as
* and vprintf. For details on the arguments and return codes it is useful to consult
* any book that describes the standard C library such as
* `The C Programming Language ANSI C Edition` by Kernighan and Ritchie.
*
*
*/
#include <stdarg.h>
@ -37,9 +37,9 @@ extern "C" {
#endif
/**
* errlogListener function type.
*
* This is used when adding or removing log listeners in ::errlogAddListener
* errlogListener function type.
*
* This is used when adding or removing log listeners in ::errlogAddListener
* and ::errlogRemoveListeners.
*/
typedef void (*errlogListener)(void *pPrivate, const char *message);
@ -52,6 +52,7 @@ typedef enum {
errlogFatal
} errlogSevEnum;
/** Boolean to control whether some messages include more detail */
LIBCOM_API extern int errVerbose;
@ -63,18 +64,19 @@ LIBCOM_API extern int errVerbose;
"fatal"
};
#else
/** String representation of errlog severity values */
LIBCOM_API extern const char * errlogSevEnumString[];
#endif
/**
* errMessage is a macro so it can get the file and line number. It prints the message,
* the status symbol and string values, and the name of the task which invoked errMessage.
* It also prints the name of the source le and the line number from which the call was issued.
/**
* errMessage is a macro so it can get the file and line number. It prints the message,
* the status symbol and string values, and the name of the task which invoked errMessage.
* It also prints the name of the source file and the line number from which the call was issued.
*
* The status code used for the 1st argument is:
* - 0: Find latest vxWorks or Unix error (errno value).
* - -1: Dont report status.
* - Other: Use this status code and lookup the string value
* - -1: Don't report status.
* - Other: Use this status code and lookup the string value
*
* \param S Status code
* \param PM The message to print
@ -90,58 +92,58 @@ LIBCOM_API extern int errVerbose;
/**
* errlogPrintf is like the printf function provided by the standard C library, except
* that the output is sent to the errlog task. Unless configured not to, the output
* will appear on the console as well.
* that the output is sent to the errlog task. Unless configured not to, the output
* will appear on the console as well.
*/
LIBCOM_API int errlogPrintf(const char *pformat, ...)
EPICS_PRINTF_STYLE(1,2);
/**
* errlogVprintf is like the vprintf function provided by the standard C library, except
* that the output is sent to the errlog task. Unless configured not to, the output
* will appear on the console as well.
* that the output is sent to the errlog task. Unless configured not to, the output
* will appear on the console as well.
*/
LIBCOM_API int errlogVprintf(const char *pformat, va_list pvar);
/**
* This function is like ::errlogPrintf except that it adds the severity to the beginning
* of the message in the form `sevr=<value>` where value is one of the enumerated
* severities in ::errlogSevEnum. Also the message is suppressed if severity is less than
* the current severity to suppress.
*
* This function is like ::errlogPrintf except that it adds the severity to the beginning
* of the message in the form `sevr=<value>` where value is one of the enumerated
* severities in ::errlogSevEnum. Also the message is suppressed if severity is less than
* the current severity to suppress.
*
* \param severity One of the severity enums from ::errlogSevEnum
* \param pFormat The message to log or print
* \return int Consult printf documentation in C standard library
* \param pformat The message to log or print
* \return int Consult printf documentation in C standard library
*/
LIBCOM_API int errlogSevPrintf(const errlogSevEnum severity,
const char *pformat, ...) EPICS_PRINTF_STYLE(2,3);
/**
* This function is like ::errlogVprintf except that it adds the severity to the beginning
* of the message in the form `sevr=<value>` where value is one of the enumerated
* severities in ::errlogSevEnum. Also the message is suppressed if severity is less than
* the current severity to suppress. If epicsThreadIsOkToBlock is true, which is
* This function is like ::errlogVprintf except that it adds the severity to the beginning
* of the message in the form `sevr=<value>` where value is one of the enumerated
* severities in ::errlogSevEnum. Also the message is suppressed if severity is less than
* the current severity to suppress. If epicsThreadIsOkToBlock is true, which is
* true during iocInit, errlogSevVprintf does NOT send output to the
* errlog task.
*
*
* \param severity One of the severity enums from ::errlogSevEnum
* \param pFormat The message to log or print
* \param pformat The message to log or print
* \param pvar va_list
* \return int Consult printf documentation in C standard library
* \return int Consult printf documentation in C standard library
*/
LIBCOM_API int errlogSevVprintf(const errlogSevEnum severity,
const char *pformat, va_list pvar);
/**
/**
* Sends message to the errlog task.
*
*
* \param message The message to send
*/
LIBCOM_API int errlogMessage(const char *message);
/**
* Gets the string value of severity.
*
*
* \param severity The severity from ::errlogSevEnum
* \return The string value
*/
@ -180,7 +182,7 @@ LIBCOM_API int errlogRemoveListeners(errlogListener listener,
/**
* Normally the errlog system displays all messages on the console.
* During error message storms this function can be used to suppress console messages.
* During error message storms this function can be used to suppress console messages.
* A argument of 0 suppresses the messages, any other value lets messages go to the console.
*
* \param yesno (0=No, 1=Yes)
@ -197,39 +199,40 @@ LIBCOM_API int eltc(int yesno);
LIBCOM_API int errlogSetConsole(FILE *stream);
/**
* Can be used to initialize the error logging system with a larger buer. The default buer size is 1280 bytes.
* Can be used to initialize the error logging system with a larger buffer. The default buffer size is 1280 bytes.
*
* \param bufsize The desired buffer size
*/
LIBCOM_API int errlogInit(int bufsize);
/**
* errlogInit2 can be used to initialize the error logging system with a larger buer and maximum message size.
* The default buer size is 1280 bytes, and the default maximum message size is 256.
* errlogInit2 can be used to initialize the error logging system with a larger buffer and maximum message size.
* The default buffer size is 1280 bytes, and the default maximum message size is 256.
*
* \param bufsize The desired buffer size
* \param maxMsgSize The desired max message size
*/
LIBCOM_API int errlogInit2(int bufsize, int maxMsgSize);
/** Wakes up the errlog task and then waits until all messages are ushed from the queue. */
/** Wakes up the errlog task and then waits until all messages are flushed from the queue. */
LIBCOM_API void errlogFlush(void);
/**
* Routine errPrintf is normally called as follows:
* `errPrintf(status, __FILE__, __LINE__,"<fmt>",...); `
*
* Where status is dened as:
* `errPrintf(status, __FILE__, __LINE__, "<fmt>", ...); `
*
* Where status is defined as:
* - 0: Find latest vxWorks or Unix error.
* - -1: Dont report status.
* - Other: Use this status code and lookup the string value
*
* - -1: Don't report status.
* - Other: Use this status code and lookup the string value
*
* \param status See above
* \param __FILE__ As shown or NULL if the le name and line number should not be printed.
* \param __LINE__ As shown
*
* The remaining arguments are just like the arguments to the C printf routine.
* ::errVerbose determines if the filename and line number are shown.
* \param pFileName As shown or NULL if the file name and line number should not be printed.
* \param lineno As shown
* \param pformat The message to log or print
*
* The remaining arguments are just like the arguments to the C printf routine.
* ::errVerbose determines if the filename and line number are shown.
*/
LIBCOM_API void errPrintf(long status, const char *pFileName, int lineno,
const char *pformat, ...) EPICS_PRINTF_STYLE(4,5);

View File

@ -102,8 +102,8 @@ typedef union epics_any {
* \brief Corresponding Type Codes
* (this enum must start at zero)
*
* !! Update \ref epicsTypeToDBR_XXXX[] and \ref DBR_XXXXToEpicsType
* in db_access.h if you edit this enum !!
* \note Update \a epicsTypeToDBR_XXXX[] and \a DBR_XXXXToEpicsType
* in db_access.h if you edit this enum
*/
typedef enum {
epicsInt8T,

View File

@ -49,7 +49,7 @@
* Additional information can be supplied using the testDiag() routine, which
* displays the relevant information as a comment in the result output. None of
* the printable strings passed to any testXxx() routine should contain a newline
* '\n' character, newlines will be added by the test routines as part of the
* '\\n' character, newlines will be added by the test routines as part of the
* Test Anything Protocol. For multiple lines of diagnostic output, call
* testDiag() as many times as necessary.
*
@ -176,8 +176,8 @@ LIBCOM_API void testPlan(int tests);
*/
LIBCOM_API 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.
/** \brief Test result using expression as description
* \param cond Expression to be evaluated and displayed.
* \return The value of \p cond.
*/
#define testOk1(cond) testOk(cond, "%s", #cond)
@ -204,7 +204,7 @@ LIBCOM_API void testFail(const char *fmt, ...)
/** @} */
/** \name Missing or Failing Tests
* \brief Routines for handling special situations.
* Routines for handling special situations.
*/
/** @{ */
@ -261,7 +261,13 @@ typedef int (*TESTFUNC)(void);
/** \brief Initialize test harness
*/
LIBCOM_API void testHarness(void);
/** \brief End of testing
*/
LIBCOM_API void testHarnessExit(void *dummy);
/** \brief Run a single test program
* \param name Program name
* \param func Function implementing test program
*/
LIBCOM_API void runTestFunc(const char *name, TESTFUNC func);
/** \brief Run a test program