Re: [PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[Jan Kiszka <jan.kiszka@siemens.com>]

On 03.09.26 12:34, Clara Kowalsky wrote:
> 
> 
> On 9/3/26 11:48, Florian Bezdeka wrote:
>> On Thu, 2026-09-03 at 10:34 +0200, Clara Kowalsky wrote:
>>> The doxygen configuration lacks a definition for COBALT_IMPL_TIME64().
>>> Therefore doxygen does not see the expanded wrapper prototype in
>>> wrappers_time64.c and instead tries to match @param entries against the
>>> macro call.
>>>
>>> This raises warnings at doc build such as
>>>
>>> lib/cobalt/wrappers_time64.c:42: warning: argument 'clock_id' of
>>> command @param is not found in the argument list of
>>> COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,(clockid_t
>>> clock_id, struct timespec *tp))
>>>
>>> as doxygen is seeing the raw macro form
>>>
>>> COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,
>>>            (clockid_t clock_id, struct timespec *tp))
>>>
>>> With the fix, doxygen rewrites the macro to
>>>
>>> int clock_getres(clockid_t clock_id, struct timespec *tp)
>>
>> Hm. The generated documentation should be "generic", right?
>>
>> Depending on the chosen build configuration clock_getres OR
>> __clock_getres64 would be correct, but that is also hidden from the user
>> in glibc land, so we should probably do the same "hiding" here.
>>
>> That said: LGTM.
> 
> The doxygen mapping should describe the stable public API, not whichever
> internal symbol is emitted for a particular time ABI. So the generated
> docs should expose only the generic API name clock_getres, regardless
> which build variant is selected.
>>
>>>
>>> It uses the first macro argument (return type), the second (function
>>> name) and fourth (parameter list), but ignores the third (alternate
>>> function name, unneeded).
>>> By this, doxygen sees the actual public function prototype.
>>> See #18.
>>>
>>> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
>>> ---
>>>   doc/doxygen/xeno3prm-common.conf.in | 1 +
>>>   1 file changed, 1 insertion(+)
>>>
>>> diff --git a/doc/doxygen/xeno3prm-common.conf.in b/doc/doxygen/
>>> xeno3prm-common.conf.in
>>> index 71db05686..ee4ede10d 100644
>>> --- a/doc/doxygen/xeno3prm-common.conf.in
>>> +++ b/doc/doxygen/xeno3prm-common.conf.in
>>> @@ -647,6 +647,7 @@ PREDEFINED = DOXYGEN_CPP            \
>>>           "EXPORT_SYMBOL_GPL(symbol)=//"        \
>>>           "DECLARE_BITMAP(symbol, nr)=unsigned long
>>> symbol[BITS_TO_LONGS(nr)]" \
>>>       "COBALT_IMPL(T,I,A)=T I A"        \
>>> +    "COBALT_IMPL_TIME64(T,I,N,A)=T I A"    \
>>>       "COBALT_DECL(T,P)=T P"            \
>>
>> No complains about COBALT_DECL_TIME64? Would have expected something
>> similar...
> 
> I built the documentation with:
> ./scripts/bootstrap
> ./configure --enable-doc-build
> make -C doc -B V=1 2>&1 | tee /tmp/xeno-doc-build.log
> 
> And checked for warnings:
> rg -i warn /tmp/xeno-doc-build.log
> 
> I didn't get any warnings for COBALT_DECL_TIME64.
> 

I guess that's because function docs are normally attached to the
implementation, not the declaration.

>>
>>>       "COBALT_SYSCALL(N,M,T,A)=T N A"        \
>>>       "COBALT_SYSCALL_DECL(N,T,A)=T N A"
>>> -- 
>>> 2.55.0
>>
>> Question to the complete series: Is
>> https://gitlab.com/Xenomai/xenomai3/xenomai/-/work_items/18 completely
>> closed with this series applied?
> 
> Yes, those 3 commits fix all doxygen warnings.
> 

Thanks! Patches 1 and 2 applied now. 3 is waiting for an update (but I
pushed it too quickly already - will be replaced).

Jan

-- 
Siemens AG, Foundational Technologies
Linux Expert Center