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/1837e3bc4726284ca8580cf80d666ff6a886765c#diff-569346abbd18a14faf916194490af4ebf6c76b4e5f92e4a1fc6ea1f85c5d447fR2069
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 defined 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 defined 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
>
>
- Replies:
- RE: [EXTERNAL] Re: errlog.h Pearson, Matthew R. via Core-talk
- References:
- errlog.h Pearson, Matthew R. via Core-talk
- Re: errlog.h Johnson, Andrew N. via Core-talk
- Navigate by Date:
- Prev:
Re: errlog.h Johnson, Andrew N. via Core-talk
- Next:
RE: [EXTERNAL] Re: errlog.h Pearson, Matthew R. via Core-talk
- Index:
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
<2021>
2022
2023
2024
- Navigate by Thread:
- Prev:
Re: errlog.h Johnson, Andrew N. via Core-talk
- Next:
RE: [EXTERNAL] Re: errlog.h Pearson, Matthew R. via Core-talk
- Index:
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
<2021>
2022
2023
2024
|