Re: [PATCH v3 1/4] serial: Convert serial_rs485 to kernel doc

[Ilpo Järvinen]

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?

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

-- 
 i.