serial: Convert serial_rs485 to kernel doc
Subsystems (2)
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
@@ -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)
Jiri Slaby
maintainerQuoted 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::flagsbits 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
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::flagsbits 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.
Jiri Slaby
maintainerQuoted 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