Skip to contentSkip to conversation

serial: Convert serial_rs485 to kernel doc

PATCH Superseded Ilpo Järvinen 2 participants 4 messages Sep 27, 2022

Subsystems (2)

v2 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 serial: Convert serial_rs485 to kernel doc

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

---
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(-)
Documentation/driver-api/serial/serial-rs485.rst +7 -6
index 6ebad75c74ed..3b3492a60ecc 100644
@@ -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
include/uapi/linux/serial.h +40 -21

77 lines not on this page · raw message

Signature · 1 line
tg: (2eb6f6da8b51..) rs485/kdoc (depends on: supported-fix/intro-kernel_serial_rs485_to_user_rs485)
maintainer
#1 lore raw
Quoted 4 lines · Ilpo Järvinen

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.

Quoted 6 lines

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

Quoted 8 lines

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

Quoted 1 line

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

regards,

Signature · 2 lines
js
suse labs
#2 lore raw
Quoted 7 lines · Jiri Slaby
Quoted 4 lines · Ilpo Järvinen

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.

Quoted 22 lines
Quoted 8 lines

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

Quoted 10 lines

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

Quoted 1 line

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.

Signature · 1 line
 i.
maintainer
#3 lore raw
In reply to Ilpo Järvinen
Quoted 28 lines · Ilpo Järvinen
Documentation/driver-api/serial/serial-rs485.rst +6 -3
@@ -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
  ========================
 

Documentation/driver-api/serial/serial-rs485.rst RS485 Serial Communications · line 132

Quoted 7 lines
Documentation/driver-api/serial/serial-rs485.rst +1 -3
@@ -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,

Signature · 2 lines
js
suse labs