From 7d2ca62a784d7199aac383167d6cf4c7a7cbde34 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Sat, 25 Sep 2021 22:34:05 -0500 Subject: [PATCH] Misc doxygen fixes and updates --- documentation/Doxyfile@ | 2 +- modules/database/src/ioc/db/dbUnitTest.h | 4 +- modules/libcom/src/error/errlog.h | 103 ++++++++++++----------- modules/libcom/src/misc/epicsTypes.h | 4 +- modules/libcom/src/misc/epicsUnitTest.h | 14 ++- 5 files changed, 68 insertions(+), 59 deletions(-) diff --git a/documentation/Doxyfile@ b/documentation/Doxyfile@ index bf53ee0ce..7f6046f48 100644 --- a/documentation/Doxyfile@ +++ b/documentation/Doxyfile@ @@ -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 diff --git a/modules/database/src/ioc/db/dbUnitTest.h b/modules/database/src/ioc/db/dbUnitTest.h index 60d4e7883..f971fe89d 100644 --- a/modules/database/src/ioc/db/dbUnitTest.h +++ b/modules/database/src/ioc/db/dbUnitTest.h @@ -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 diff --git a/modules/libcom/src/error/errlog.h b/modules/libcom/src/error/errlog.h index 02f2c0816..af30c4f5f 100644 --- a/modules/libcom/src/error/errlog.h +++ b/modules/libcom/src/error/errlog.h @@ -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 @@ -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 file 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: Don’t 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=` 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=` 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=` 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=` 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 buffer. The default buffer 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 buffer and maximum message size. - * The default buffer 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 flushed 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__,"",...); ` - * - * Where status is defined as: + * `errPrintf(status, __FILE__, __LINE__, "", ...); ` + * + * Where status is defined as: * - 0: Find latest vxWorks or Unix error. - * - -1: Don’t 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 file 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); diff --git a/modules/libcom/src/misc/epicsTypes.h b/modules/libcom/src/misc/epicsTypes.h index c3f713ed3..432c8961c 100644 --- a/modules/libcom/src/misc/epicsTypes.h +++ b/modules/libcom/src/misc/epicsTypes.h @@ -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, diff --git a/modules/libcom/src/misc/epicsUnitTest.h b/modules/libcom/src/misc/epicsUnitTest.h index 66dd8f281..923890382 100644 --- a/modules/libcom/src/misc/epicsUnitTest.h +++ b/modules/libcom/src/misc/epicsUnitTest.h @@ -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