On 9/29/22 15:39, Ilpo Järvinen wrote: > On Thu, 29 Sep 2022, Bagas Sanjaya wrote: > >> On Wed, Sep 28, 2022 at 02:05:06PM +0300, Ilpo Järvinen wrote: >>> diff --git a/include/uapi/linux/serial.h b/include/uapi/linux/serial.h >>> index cea06924b295..6e347eb10b1f 100644 >>> --- a/include/uapi/linux/serial.h >>> +++ b/include/uapi/linux/serial.h >>> @@ -107,37 +107,57 @@ struct serial_icounter_struct { >>> int reserved[9]; >>> }; >>> >>> -/* >>> +/** >>> + * struct serial_rs485 - serial interface for controlling RS485 settings. >>> + * @flags: RS485 feature flags. >>> + * @delay_rts_before_send: Delay before send (milliseconds). >>> + * @delay_rts_after_send: Delay after send (milliseconds). >>> + * @addr_recv: Receive filter for RS485 addressing mode >>> + * (used only when %SER_RS485_ADDR_RECV is set). >>> + * @addr_dest: Destination address for RS485 addressing mode >>> + * (used only when %SER_RS485_ADDR_DEST is set). >>> + * @padding0: Padding (set to zero). >>> + * @padding1: Padding (set to zero). >>> + * @padding: Deprecated, use @padding0 and @padding1 instead. >>> + * Do not use with @addr_recv and @addr_dest (due to >>> + * overlap). >>> + * >> >> I don't see definition of fields after @delay_rts_after_send in the >> htmldocs output. > > So it seems, this one I had missed. I guess the reason is that those > members are inside anonymous unions. But the formatting follows what > is documented here AFAICT: > > https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#nested-structs-unions > > Kerneldoc doesn't seem to live up to what is documented about it. It's a > bit ironic that documentation system fails to document even itself to > sufficient level, and what's worse, seems to be full of faulty examples. > > Any suggestions how to make it work? > CC'ing Akira. >>> * Serial interface for controlling RS485 settings on chips with suitable >>> * support. Set with TIOCSRS485 and get with TIOCGRS485 if supported by your >>> * platform. The set function returns the new state, with any unsupported bits >>> * reverted appropriately. >>> + * >>> + * serial_rs485::flags bits are: >>> + * >>> + * * %SER_RS485_ENABLED - RS485 enabled. >>> + * * %SER_RS485_RTS_ON_SEND - Logical level for RTS pin when sending. >>> + * * %SER_RS485_RTS_AFTER_SEND - Logical level for RTS pin after sent. >>> + * * %SER_RS485_RX_DURING_TX - Full-duplex RS485 line. >>> + * * %SER_RS485_TERMINATE_BUS - Enable bus termination (if supported). >>> + * * %SER_RS485_ADDRB - Enable RS485 addressing mode. >>> + * * %SER_RS485_ADDR_RECV - Receive address filter (enables @addr_recv). >>> + * Requires %SER_RS485_ADDRB. >>> + * * %SER_RS485_ADDR_DEST - Destination address (enables @addr_dest). >>> + * Requires %SER_RS485_ADDRB. >> >> The last two items are rendered as bold text instead (maybe due to missing >> fields rendering above?) > > It just goes into some random formatting mode here. Even if I remove those > field markers (@) it doesn't do formatting differently so your guesss is > wrong. > > I found now a way to make it work though. It works when I put the whole > description on a single line but it comes at the cost of removing the > alignment of those "-". The other way to make it work would be like this: > > * * %SER_RS485_ADDR_RECV - Receive address filter (enables @addr_recv). > Requires %SER_RS485_ADDRB. > > ...And that's no good. I guess the single-line approach is an acceptable > compromise for this case. > OK, thanks for explaining. -- An old man doll... just what I always wanted! - Clara