Experimental Physics and
Industrial Control System

"Pearson, Matthew R. via Core-talk" <core-talk at aps.anl.gov> · Tue, 9 Mar 2021 19:15:32 +0000

Hi,

Thanks. I had pulled in the latest changes.

I found the problem though. In the prior function comment I had "\code", which isn't valid, and it must have caused the parser to skip the rest of the file. Once I fixed that, the functions appeared.

I'll update my pull request with the fix.

Cheers,
Matt

> -----Original Message-----
> From: Michael Davidsaver <mdavidsaver at gmail.com>
> Sent: Tuesday, March 9, 2021 1:04 PM
> To: Johnson, Andrew N. <anj at anl.gov>; Pearson, Matthew R.
> <pearsonmr at ornl.gov>
> Cc: Andrew Johnson via Core-talk <core-talk at aps.anl.gov>
> Subject: [EXTERNAL] Re: errlog.h
> 
> On 3/9/21 9:53 AM, Johnson, Andrew N. via Core-talk wrote:
> > 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.
> 
> 
> It may, or may not, be relevant.  With PVXS I've settled on
> MACRO_EXPANSION=YES, EXPAND_ONLY_PREDEF=YES, and
> EXPAND_AS_DEFINED=PVXS_API to get the effect I wanted.  Not having the
> dllimport/export macros messing things up.  I don't recall having problems
> with function macros, though I do have a couple:
> 
> https://github.com/mdavidsaver/pvxs/commit/1837e3bc4726284ca8580cf80
> d666ff6a886765c#diff-
> 569346abbd18a14faf916194490af4ebf6c76b4e5f92e4a1fc6ea1f85c5d447fR2
> 069
> 
> eg. documented function macros:
> https://mdavidsaver.github.io/pvxs/util.html#c.log_crit_printf
> 
> 
> >> 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
> >
> >

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System