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
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 <[email protected]>
---
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
Convert struct serial_rs485 comments to kernel doc format and include
it into documentation.
Suggested-by: Andy Shevchenko <[email protected]>
Signed-off-by: Ilpo Järvinen <[email protected]>
---
.../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
Use "struct serial_rs485" to get the references properly recognized.
Signed-off-by: Ilpo Järvinen <[email protected]>
---
.../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
On Wed, Sep 28, 2022 at 2:05 PM Ilpo Järvinen
<[email protected]> 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 <[email protected]>
> 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
Link DT bindings reference properly.
Signed-off-by: Ilpo Järvinen <[email protected]>
---
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
On Wed, Sep 28, 2022 at 2:05 PM Ilpo Järvinen
<[email protected]> 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
On Wed, 28 Sep 2022, Andy Shevchenko wrote:
> On Wed, Sep 28, 2022 at 2:05 PM Ilpo Järvinen
> <[email protected]> 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.
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
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.
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
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.