[PATCH v2] serial: Convert serial_rs485 to kernel doc

[PATCH v2] serial: Convert serial_rs485 to kernel doc

[Ilpo Järvinen]

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

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>

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

For reasons unknown to me, the formatting in the flags doesn't produce the
effect promised by kerneldoc's documentation:

  https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values


 Documentation/driver-api/serial/serial-rs485.rst | 13 ++---
 include/uapi/linux/serial.h                      | 61 ++++++++++++++++--------
 2 files changed, 47 insertions(+), 27 deletions(-)

diff --git a/Documentation/driver-api/serial/serial-rs485.rst b/Documentation/driver-api/serial/serial-rs485.rst
index 6ebad75c74ed..3b3492a60ecc 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..47b09d8c2fe7 100644
--- a/include/uapi/linux/serial.h
+++ b/include/uapi/linux/serial.h
@@ -107,37 +107,56 @@ 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;

-- 
tg: (2eb6f6da8b51..) rs485/kdoc (depends on: supported-fix/intro-kernel_serial_rs485_to_user_rs485)

Re: [PATCH v2] serial: Convert serial_rs485 to kernel doc

[Jiri Slaby]

On 27. 09. 22, 12:47, Ilpo Järvinen wrote:
> For reasons unknown to me, the formatting in the flags doesn't produce the
> effect promised by kerneldoc's documentation:
> 
>    https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values

Returns are special.

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

Put one more \n here.

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

And perhaps remove the second * here?

> + * * %SER_RS485_ADDR_DEST	- Destination address (enables @addr_dest).

regards,
-- 
js
suse labs

Re: [PATCH v2] serial: Convert serial_rs485 to kernel doc

[Jiri Slaby]

On 27. 09. 22, 12:47, Ilpo Järvinen wrote:
> --- 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

BTW could that [1] be converted into proper hyperlink too (separately)?

thanks,
-- 
js
suse labs

Re: [PATCH v2] serial: Convert serial_rs485 to kernel doc

[Ilpo Järvinen]

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

On Tue, 27 Sep 2022, Jiri Slaby wrote:

> On 27. 09. 22, 12:47, Ilpo Järvinen wrote:
> > For reasons unknown to me, the formatting in the flags doesn't produce the
> > effect promised by kerneldoc's documentation:
> > 
> >    https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
> 
> Returns are special.

Might be but I understood that formatting thing to be more general.

> >    * 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:
> 
> Put one more \n here.
> 
> > + * * %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.
> 
> And perhaps remove the second * here?

It gave me error earlier but now when I added also that newline above you 
suggested, it seems to no longer triggers the error. Thus, I ended up 
making both of the changes you suggested.


-- 
 i.