[PATCH v3 0/4] serial: RS485 kerneldoc/documentation improvements

[PATCH v3 0/4] serial: RS485 kerneldoc/documentation improvements

[Ilpo Järvinen]

RS485 documentation improvements. While doing the kerneldoc conversion,
a few other items came up so they're now included to this series.

v3:
- More fixes to kernel doc formatting (thanks to Jiri)
- Added a few other related improvements

v2:
- Include serial_rs485 into documentation
- Add * to multi-line flag descriptions


Ilpo Järvinen (4):
  serial: Convert serial_rs485 to kernel doc
  Documentation: rs485: Link reference properly
  Documentation: rs485: Mention uart_get_rs485_mode()
  Documentation: rs485: Fix struct referencing

 .../driver-api/serial/serial-rs485.rst        | 36 ++++++-----
 include/uapi/linux/serial.h                   | 62 ++++++++++++-------
 2 files changed, 60 insertions(+), 38 deletions(-)

-- 
2.30.2

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

[Ilpo Järvinen]

Convert struct serial_rs485 comments to kernel doc format and include
it into documentation.

Suggested-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
---
 .../driver-api/serial/serial-rs485.rst        | 13 ++--
 include/uapi/linux/serial.h                   | 62 ++++++++++++-------
 2 files changed, 48 insertions(+), 27 deletions(-)

diff --git a/Documentation/driver-api/serial/serial-rs485.rst b/Documentation/driver-api/serial/serial-rs485.rst
index 6ebad75c74ed..264e4b753713 100644
--- a/Documentation/driver-api/serial/serial-rs485.rst
+++ b/Documentation/driver-api/serial/serial-rs485.rst
@@ -29,11 +29,11 @@ RS485 Serial Communications
 3. Data Structures Already Available in the Kernel
 ==================================================
 
-   The Linux kernel provides the serial_rs485 structure (see [1]) to handle
-   RS485 communications. This data structure is used to set and configure RS485
+   The Linux kernel provides the serial_rs485 structure to handle RS485
+   communications. This data structure is used to set and configure RS485
    parameters in the platform data and in ioctls.
 
-   The device tree can also provide RS485 boot time parameters (see [2]
+   The device tree can also provide RS485 boot time parameters (see [1]
    for bindings). The driver is in charge of filling this data structure from
    the values given by the device tree.
 
@@ -47,6 +47,9 @@ RS485 Serial Communications
    for the uart_port. TIOCGRS485 ioctl can be used to read back the
    serial_rs485 structure matching to the current configuration.
 
+.. kernel-doc:: include/uapi/linux/serial.h
+   :identifiers: serial_rs485
+
 4. Usage from user-level
 ========================
 
@@ -126,6 +129,4 @@ RS485 Serial Communications
 6. References
 =============
 
- [1]	include/uapi/linux/serial.h
-
- [2]	Documentation/devicetree/bindings/serial/rs485.txt
+ [1]	Documentation/devicetree/bindings/serial/rs485.txt
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).
+ *
  * 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.
  */
-
 struct serial_rs485 {
-	__u32	flags;			/* RS485 feature flags */
-#define SER_RS485_ENABLED		(1 << 0)	/* If enabled */
-#define SER_RS485_RTS_ON_SEND		(1 << 1)	/* Logical level for
-							   RTS pin when
-							   sending */
-#define SER_RS485_RTS_AFTER_SEND	(1 << 2)	/* Logical level for
-							   RTS pin after sent*/
+	__u32	flags;
+#define SER_RS485_ENABLED		(1 << 0)
+#define SER_RS485_RTS_ON_SEND		(1 << 1)
+#define SER_RS485_RTS_AFTER_SEND	(1 << 2)
 #define SER_RS485_RX_DURING_TX		(1 << 4)
-#define SER_RS485_TERMINATE_BUS		(1 << 5)	/* Enable bus
-							   termination
-							   (if supported) */
-
-/* RS-485 addressing mode */
-#define SER_RS485_ADDRB			(1 << 6)	/* Enable addressing mode */
-#define SER_RS485_ADDR_RECV		(1 << 7)	/* Receive address filter */
-#define SER_RS485_ADDR_DEST		(1 << 8)	/* Destination address */
+#define SER_RS485_TERMINATE_BUS		(1 << 5)
+#define SER_RS485_ADDRB			(1 << 6)
+#define SER_RS485_ADDR_RECV		(1 << 7)
+#define SER_RS485_ADDR_DEST		(1 << 8)
 
-	__u32	delay_rts_before_send;	/* Delay before send (milliseconds) */
-	__u32	delay_rts_after_send;	/* Delay after send (milliseconds) */
+	__u32	delay_rts_before_send;
+	__u32	delay_rts_after_send;
 
-	/* The fields below are defined by flags */
+	/* private: The fields below are defined by flags */
 	union {
-		__u32	padding[5];		/* Memory is cheap, new structs are a pain */
+		/* private: Memory is cheap, new structs are a pain. */
+		__u32	padding[5];
 
 		struct {
 			__u8	addr_recv;
-- 
2.30.2

[PATCH v3 2/4] Documentation: rs485: Link reference properly

[Ilpo Järvinen]

Link DT bindings reference properly.

Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
---
 Documentation/driver-api/serial/serial-rs485.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/serial/serial-rs485.rst b/Documentation/driver-api/serial/serial-rs485.rst
index 264e4b753713..513758a702a6 100644
--- a/Documentation/driver-api/serial/serial-rs485.rst
+++ b/Documentation/driver-api/serial/serial-rs485.rst
@@ -33,9 +33,9 @@ RS485 Serial Communications
    communications. This data structure is used to set and configure RS485
    parameters in the platform data and in ioctls.
 
-   The device tree can also provide RS485 boot time parameters (see [1]
-   for bindings). The driver is in charge of filling this data structure from
-   the values given by the device tree.
+   The device tree can also provide RS485 boot time parameters
+   [#DT-bindings]_. The driver is in charge of filling this data structure
+   from the values given by the device tree.
 
    Any driver for devices capable of working both as RS232 and RS485 should
    implement the rs485_config callback and provide rs485_supported in the
@@ -129,4 +129,4 @@ RS485 Serial Communications
 6. References
 =============
 
- [1]	Documentation/devicetree/bindings/serial/rs485.txt
+.. [#DT-bindings]	Documentation/devicetree/bindings/serial/rs485.txt
-- 
2.30.2

[PATCH v3 3/4] Documentation: rs485: Mention uart_get_rs485_mode()

[Ilpo Järvinen]

Add to rs485 documentation that serial core prepares the struct
serial_rs485 when uart_get_rs485_mode() is called. Remove the wrong
claim that driver must fill it by itself.

Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
---
 Documentation/driver-api/serial/serial-rs485.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/serial/serial-rs485.rst b/Documentation/driver-api/serial/serial-rs485.rst
index 513758a702a6..2951dacfb9eb 100644
--- a/Documentation/driver-api/serial/serial-rs485.rst
+++ b/Documentation/driver-api/serial/serial-rs485.rst
@@ -34,8 +34,8 @@ RS485 Serial Communications
    parameters in the platform data and in ioctls.
 
    The device tree can also provide RS485 boot time parameters
-   [#DT-bindings]_. The driver is in charge of filling this data structure
-   from the values given by the device tree.
+   [#DT-bindings]_. The serial core fills the struct serial_rs485 from the
+   values given by the device tree when driver calls uart_get_rs485_mode().
 
    Any driver for devices capable of working both as RS232 and RS485 should
    implement the rs485_config callback and provide rs485_supported in the
@@ -48,7 +48,7 @@ RS485 Serial Communications
    serial_rs485 structure matching to the current configuration.
 
 .. kernel-doc:: include/uapi/linux/serial.h
-   :identifiers: serial_rs485
+   :identifiers: serial_rs485 uart_get_rs485_mode
 
 4. Usage from user-level
 ========================
-- 
2.30.2

[PATCH v3 4/4] Documentation: rs485: Fix struct referencing

[Ilpo Järvinen]

Use "struct serial_rs485" to get the references properly recognized.

Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
---
 .../driver-api/serial/serial-rs485.rst        | 21 ++++++++++---------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/Documentation/driver-api/serial/serial-rs485.rst b/Documentation/driver-api/serial/serial-rs485.rst
index 2951dacfb9eb..d902f9de0b0f 100644
--- a/Documentation/driver-api/serial/serial-rs485.rst
+++ b/Documentation/driver-api/serial/serial-rs485.rst
@@ -29,7 +29,7 @@ RS485 Serial Communications
 3. Data Structures Already Available in the Kernel
 ==================================================
 
-   The Linux kernel provides the serial_rs485 structure to handle RS485
+   The Linux kernel provides the struct serial_rs485 to handle RS485
    communications. This data structure is used to set and configure RS485
    parameters in the platform data and in ioctls.
 
@@ -39,13 +39,14 @@ RS485 Serial Communications
 
    Any driver for devices capable of working both as RS232 and RS485 should
    implement the rs485_config callback and provide rs485_supported in the
-   uart_port structure. The serial core calls rs485_config to do the device
-   specific part in response to TIOCSRS485 ioctl (see below). The rs485_config
-   callback receives a pointer to a sanitizated serial_rs485 structure. The
-   serial_rs485 userspace provides is sanitized before calling rs485_config
-   using rs485_supported that indicates what RS485 features the driver supports
-   for the uart_port. TIOCGRS485 ioctl can be used to read back the
-   serial_rs485 structure matching to the current configuration.
+   struct uart_port. The serial core calls rs485_config to do the device
+   specific part in response to TIOCSRS485 ioctl (see below). The
+   rs485_config callback receives a pointer to a sanitizated struct
+   serial_rs485. The struct serial_rs485 userspace provides is sanitized
+   before calling rs485_config using rs485_supported that indicates what
+   RS485 features the driver supports for the struct uart_port. TIOCGRS485
+   ioctl can be used to read back the struct serial_rs485 matching to the
+   current configuration.
 
 .. kernel-doc:: include/uapi/linux/serial.h
    :identifiers: serial_rs485 uart_get_rs485_mode
@@ -107,8 +108,8 @@ RS485 Serial Communications
 
    The Linux kernel provides addressing mode for multipoint RS-485 serial
    communications line. The addressing mode is enabled with SER_RS485_ADDRB
-   flag in serial_rs485. Struct serial_rs485 has two additional flags and
-   fields for enabling receive and destination addresses.
+   flag in struct serial_rs485. The struct serial_rs485 has two additional
+   flags and fields for enabling receive and destination addresses.
 
    Address mode flags:
 	- SER_RS485_ADDRB: Enabled addressing mode (sets also ADDRB in termios).
-- 
2.30.2

Re: [PATCH v3 3/4] Documentation: rs485: Mention uart_get_rs485_mode()

[Andy Shevchenko]

On Wed, Sep 28, 2022 at 2:05 PM Ilpo Järvinen
<ilpo.jarvinen@linux.intel.com> wrote:
>
> Add to rs485 documentation that serial core prepares the struct
> serial_rs485 when uart_get_rs485_mode() is called. Remove the wrong
> claim that driver must fill it by itself.

the driver

...

>     The device tree can also provide RS485 boot time parameters
> -   [#DT-bindings]_. The driver is in charge of filling this data structure
> -   from the values given by the device tree.
> +   [#DT-bindings]_. The serial core fills the struct serial_rs485 from the
> +   values given by the device tree when driver calls uart_get_rs485_mode().

the driver

Feels like this should be before the previous patch and actually have
a Fixes tag.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v3 0/4] serial: RS485 kerneldoc/documentation improvements

[Andy Shevchenko]

On Wed, Sep 28, 2022 at 2:05 PM Ilpo Järvinen
<ilpo.jarvinen@linux.intel.com> wrote:
>
> RS485 documentation improvements. While doing the kerneldoc conversion,
> a few other items came up so they're now included to this series.

in this


LGTM, thanks!

Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>

> v3:
> - More fixes to kernel doc formatting (thanks to Jiri)
> - Added a few other related improvements
>
> v2:
> - Include serial_rs485 into documentation
> - Add * to multi-line flag descriptions
>
>
> Ilpo Järvinen (4):
>   serial: Convert serial_rs485 to kernel doc
>   Documentation: rs485: Link reference properly
>   Documentation: rs485: Mention uart_get_rs485_mode()
>   Documentation: rs485: Fix struct referencing
>
>  .../driver-api/serial/serial-rs485.rst        | 36 ++++++-----
>  include/uapi/linux/serial.h                   | 62 ++++++++++++-------
>  2 files changed, 60 insertions(+), 38 deletions(-)
>
> --
> 2.30.2
>


-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v3 3/4] Documentation: rs485: Mention uart_get_rs485_mode()

[Ilpo Järvinen]

[-- Attachment #1: Type: text/plain, Size: 758 bytes --]

On Wed, 28 Sep 2022, Andy Shevchenko wrote:

> On Wed, Sep 28, 2022 at 2:05 PM Ilpo Järvinen
> <ilpo.jarvinen@linux.intel.com> wrote:
> 
> >     The device tree can also provide RS485 boot time parameters
> > -   [#DT-bindings]_. The driver is in charge of filling this data structure
> > -   from the values given by the device tree.
> > +   [#DT-bindings]_. The serial core fills the struct serial_rs485 from the
> > +   values given by the device tree when driver calls uart_get_rs485_mode().
> 
> the driver
> 
> Feels like this should be before the previous patch and actually have
> a Fixes tag.

I don't feel it would be an appropriate tag for this kind of cases 
where documentation is simply lacking behind what the core code now 
offers.

-- 
 i.

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2297 bytes --]

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.

>   * 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?)

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Ilpo Järvinen]

[-- Attachment #1: Type: text/plain, Size: 3418 bytes --]

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.

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

[Bagas Sanjaya]

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

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

[Ilpo Järvinen]

[-- Attachment #1: Type: text/plain, Size: 2082 bytes --]

On Thu, 29 Sep 2022, Bagas Sanjaya wrote:

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

Nevermind, I figured out where the problem is (my incorrect use of 
private: markers).

-- 
 i.