michallenc commented on issue #16432:
URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2907727108
> As far as I remember Gregory was always against cluttering the code with
metadata comments like Doxygen. Personally I agree with this view. The code
should first be readable by users, not generators. Unfortunately this makes
auto-generating API documentation not so easy.
That's a fair point, but we already have comments in the code (include large
blocks for functions). There isn't much difference in readability between,
let's say.
```
begin_packed_struct struct adc_msg_s
{
uint8_t am_channel; /* The 8-bit ADC Channel */
int32_t am_data; /* ADC convert result (4 bytes) */
} end_packed_struct;
```
and
```
begin_packed_struct struct adc_msg_s
{
/*! The 8-bit ADC Channel */
uint8_t am_channel;
/*! ADC convert result (4 bytes) */
int32_t am_data;
} end_packed_struct;
```
Yes, it can get a bit messy when referencing other structures, functions,
members, etc (`@ref xyz` etc). But maybe the public API is not as critical for
automatic generation, because we don't expect it to change.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscr...@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
