Experimental Physics and
Industrial Control System

"Johnson, Andrew N. via Core-talk" <core-talk at aps.anl.gov> · Tue, 9 Mar 2021 17:53:02 +0000

Hi Matt,

On Mar 9, 2021, at 9:20 AM, Pearson, Matthew R. via Core-talk <core-talk at aps.anl.gov> wrote:
> I'm documenting functions in errlog.h. This may be more a doxygen question, but anyone know why doxygen would ignore certain functions that are in a header file?
> 
> There's a few functions in errloh.h that don't make it into the function list in the generated HTML file:
> 
> LIBCOM_API int errlogPrintfNoConsole(const char *pformat, ...)
>    EPICS_PRINTF_STYLE(1,2);
> LIBCOM_API int errlogVprintfNoConsole(const char *pformat,va_list pvar);
> LIBCOM_API void errSymLookup(long status, char *pBuf, size_t bufLength);
> 
> I tried adding a doxygen comment section to one of these, but it still didn't appear.

This switch in the documentation/Doxyfile@ might change the behaviour you’re seeing, please let me know if it helps:

> # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
> # remove all references to function-like macros that are alone on a line, have
> # an all uppercase name, and do not end with a semicolon. Such function macros
> # are typically used for boiler-plate code, and will confuse the parser if not
> # removed.
> # The default value is: YES.
> # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
> 
> SKIP_FUNCTION_MACROS   = NO

That was one of the settings I changed in my commit last night, so if you didn’t pull my changes from the 7.0 branch yet your setting might still be YES.

> Also, separate question... the IOC developers guide, when it describes errPrintf, has this section:
> 
> errPrintf(status, __FILE__, __LINE__,"<fmt>",...);
> Where status is deﬁned as:
> 
> 0: Find latest vxWorks or Unix error.
> -1: Don’t report status.
> Other: See “Return Status Values”, above.
> 
> There doesn't seem to be a "Return Status Values" section as far as I can see. I've modified the doxygen comment to be the following, based on what I think it's meant to be doing:
> 
> * Where status is deﬁned as:
> * - 0: Find latest vxWorks or Unix error.
> * - -1: Don’t report status.
> * - Other: Use this status code and lookup the string value

That looks fine to me, thanks.

> If that looks correct, should I also update the IOC developers guide too?

There is no AppDevGuide for the 7.0 branch, we’ve been splitting it up so all the API documentation will come from these Doxygen annotations.

- Andrew

-- 
Complexity comes for free, simplicity you have to work for.

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System