Experimental Physics and
Industrial Control System

Michael Davidsaver via Core-talk <core-talk at aps.anl.gov> · Tue, 9 Mar 2021 12:05:55 -0800

On 3/9/21 11:15 AM, Pearson, Matthew R. wrote:
> 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.

\code always needs a matching \endcode

> 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