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

[Clara Kowalsky <clara.kowalsky@siemens.com>]

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.

> 
>>   	"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.

BR,
Clara