Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <71effcc8-7345-28cd-6585-eb729fb4c6db@gmail.com>
Date:   Thu, 29 Sep 2022 15:50:29 +0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.13.1
Subject: Re: [PATCH v3 1/4] serial: Convert serial_rs485 to kernel doc
Content-Language: en-US
To:     =?UTF-8?Q?Ilpo_J=c3=a4rvinen?= <ilpo.jarvinen@linux.intel.com>,
        linux-doc@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Cc:     Jiri Slaby <jirislaby@kernel.org>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        linux-serial <linux-serial@vger.kernel.org>,
        LKML <linux-kernel@vger.kernel.org>,
        Andy Shevchenko <andy.shevchenko@gmail.com>,
        Akira Yokosawa <akiyks@gmail.com>
References: <20220928110509.13544-1-ilpo.jarvinen@linux.intel.com>
 <20220928110509.13544-2-ilpo.jarvinen@linux.intel.com>
 <YzURJa1RnxP+uj5/@debian.me>
 <75f07dbe-d1dd-ac18-5c8e-e6972e7fb28b@linux.intel.com>
From:   Bagas Sanjaya <bagasdotme@gmail.com>
In-Reply-To: <75f07dbe-d1dd-ac18-5c8e-e6972e7fb28b@linux.intel.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Precedence: bulk

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