[PATCH] Documentation: ABI: fix brackets and bracelets

[PATCH] Documentation: ABI: fix brackets and bracelets

[Manuel Ebner]

Fix missing and needless brackets
Fix missing bracelets

Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
---
 Documentation/ABI/stable/sysfs-class-infiniband      | 4 ++--
 Documentation/ABI/testing/sysfs-bus-iio              | 4 ++--
 Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192   | 2 +-
 Documentation/ABI/testing/sysfs-firmware-dmi-entries | 2 +-
 Documentation/ABI/testing/sysfs-firmware-gsmi        | 2 +-
 Documentation/ABI/testing/sysfs-uevent               | 2 +-
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband
index 694f23a03a28..e48a0d2fb4e5 100644
--- a/Documentation/ABI/stable/sysfs-class-infiniband
+++ b/Documentation/ABI/stable/sysfs-class-infiniband
@@ -157,8 +157,8 @@ Description:
 		all VLs from this port. This may include packets with errors.
 		This is 64 bit counter.
 
-		port_rcv_packets: (RO) Total number of packets (this may include
-		packets containing Errors. This is 64 bit counter.
+		port_rcv_packets: (RO) Total number of packets, this may include
+		packets containing Errors. This is a 64 bit counter.
 
 		link_downed: (RO) Total number of times the Port Training state
 		machine has failed the link error recovery process and downed
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index d8d6d85235b0..83471072cff0 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -917,7 +917,7 @@ Description:
 
 		Note the driver will assume the last p events requested are
 		to be enabled where p is how many it supports (which may vary
-		depending on the exact set requested. So if you want to be
+		depending on the exact set requested). So if you want to be
 		sure you have set what you think you have, check the contents of
 		these attributes after everything is configured. Drivers may
 		have to buffer any parameters so that they are consistent when
@@ -973,7 +973,7 @@ Description:
 
 		Note the driver will assume the last p events requested are
 		to be enabled where p is however many it supports (which may
-		vary depending on the exact set requested. So if you want to be
+		vary depending on the exact set requested). So if you want to be
 		sure you have set what you think you have, check the contents of
 		these attributes after everything is configured. Drivers may
 		have to buffer any parameters so that they are consistent when
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192 b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
index 28be1cabf112..108ea0abbdb6 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
@@ -16,7 +16,7 @@ Description:
 		In bridge applications, such as strain gauges and load cells,
 		the bridge itself consumes the majority of the current in the
 		system. To minimize the current consumption of the system,
-		the bridge can be disconnected (when it is not being used
+		the bridge can be disconnected when it is not being used
 		using the bridge_switch_en attribute.
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltage2-voltage2_shorted_raw
diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
index b6c23807b804..ed7d9d06a9ff 100644
--- a/Documentation/ABI/testing/sysfs-firmware-dmi-entries
+++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
@@ -93,7 +93,7 @@ Description:
 		  /sys/firmware/dmi/entries/15-0/system_event_log
 
 		and has the following attributes (documented in the
-		SMBIOS / DMI specification under "System Event Log (Type 15)":
+		SMBIOS / DMI specification under "System Event Log (Type 15)"):
 
 		- area_length
 		- header_start_offset
diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi
index 7a558354c1ee..88ca75d323d1 100644
--- a/Documentation/ABI/testing/sysfs-firmware-gsmi
+++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
@@ -18,7 +18,7 @@ Description:
 
 		/sys/firmware/gsmi/vars:
 
-			This directory has the same layout (and
+			This directory has the same layout and
 			underlying implementation as /sys/firmware/efi/vars.
 			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
 			for more information on how to interact with
diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
index 0b6227706b35..c15e18c47a0e 100644
--- a/Documentation/ABI/testing/sysfs-uevent
+++ b/Documentation/ABI/testing/sysfs-uevent
@@ -8,7 +8,7 @@ Description:
 
                 Recognized extended format is::
 
-			ACTION [UUID [KEY=VALUE ...]
+			ACTION [UUID [KEY=VALUE ...]]
 
                 The ACTION is compulsory - it is the name of the uevent
                 action (``add``, ``change``, ``remove``). There is no change
-- 
2.54.0

Re: [PATCH] Documentation: ABI: fix brackets and bracelets

[Jonathan Cameron]

On Thu, 11 Jun 2026 10:56:21 +0200
Manuel Ebner <manuelebner@mailbox.org> wrote:

> Fix missing and needless brackets
> Fix missing bracelets
> 
> Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
> ---
>  Documentation/ABI/stable/sysfs-class-infiniband      | 4 ++--
>  Documentation/ABI/testing/sysfs-bus-iio              | 4 ++--
>  Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192   | 2 +-

Take a look at hos this stuff is routed into upstream.  Each 
subsystem 'owns' their own documentation.  So this needs splitting up
on a per subsystem basis.  I'll also note that you've only +CC IIO folk
so you aren't going to get much review on the rest!

A few comments inline.

>  Documentation/ABI/testing/sysfs-firmware-dmi-entries | 2 +-
>  Documentation/ABI/testing/sysfs-firmware-gsmi        | 2 +-
>  Documentation/ABI/testing/sysfs-uevent               | 2 +-
>  6 files changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband
> index 694f23a03a28..e48a0d2fb4e5 100644
> --- a/Documentation/ABI/stable/sysfs-class-infiniband
> +++ b/Documentation/ABI/stable/sysfs-class-infiniband
> @@ -157,8 +157,8 @@ Description:
>  		all VLs from this port. This may include packets with errors.
>  		This is 64 bit counter.
>  
> -		port_rcv_packets: (RO) Total number of packets (this may include
> -		packets containing Errors. This is 64 bit counter.
> +		port_rcv_packets: (RO) Total number of packets, this may include
> +		packets containing Errors. This is a 64 bit counter.
Comma doesn't feel like the right choice here.  Perhaps,

		port_rc_packets: (RO) Total number of packets. May include
		packets containing Errors. This is a 64 bit counter.

Or just add the closing bracket.

>  
>  		link_downed: (RO) Total number of times the Port Training state
>  		machine has failed the link error recovery process and downed
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192 b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> index 28be1cabf112..108ea0abbdb6 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> @@ -16,7 +16,7 @@ Description:
>  		In bridge applications, such as strain gauges and load cells,
>  		the bridge itself consumes the majority of the current in the
>  		system. To minimize the current consumption of the system,
> -		the bridge can be disconnected (when it is not being used
> +		the bridge can be disconnected when it is not being used
>  		using the bridge_switch_en attribute.

I think intent would be better reflected here by adding the closing )
That last bit is kind of a 'by the way' rather than the dominant point of
the sentence.

>  
>  What:		/sys/bus/iio/devices/iio:deviceX/in_voltage2-voltage2_shorted_raw

> diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi
> index 7a558354c1ee..88ca75d323d1 100644
> --- a/Documentation/ABI/testing/sysfs-firmware-gsmi
> +++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
> @@ -18,7 +18,7 @@ Description:
>  
>  		/sys/firmware/gsmi/vars:
>  
> -			This directory has the same layout (and
> +			This directory has the same layout and
>  			underlying implementation as /sys/firmware/efi/vars.
>  			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
>  			for more information on how to interact with
I think I'd add the bracket after implementation as this file is about ABI
so that's less important than the rest of the sentence.

Re: [PATCH] Documentation: ABI: fix brackets and bracelets

[Manuel Ebner]

On Thu, 2026-06-11 at 10:46 +0100, Jonathan Cameron wrote:
> On Thu, 11 Jun 2026 10:56:21 +0200
> Manuel Ebner <manuelebner@mailbox.org> wrote:
> 
> > Fix missing and needless brackets
> > Fix missing bracelets
> > 
> > Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
> > ---
> >  Documentation/ABI/stable/sysfs-class-infiniband      | 4 ++--
> >  Documentation/ABI/testing/sysfs-bus-iio              | 4 ++--
> >  Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192   | 2 +-
> 
> Take a look at hos this stuff is routed into upstream.  Each 
> subsystem 'owns' their own documentation.  So this needs splitting up
> on a per subsystem basis.  I'll also note that you've only +CC IIO folk
> so you aren't going to get much review on the rest!

I send it to the addresses get_maintainer returned, except the git blame
ones. How can I find out who to send this to?

> A few comments inline.
> 
> >  Documentation/ABI/testing/sysfs-firmware-dmi-entries | 2 +-
> >  Documentation/ABI/testing/sysfs-firmware-gsmi        | 2 +-
> >  Documentation/ABI/testing/sysfs-uevent               | 2 +-
> >  6 files changed, 8 insertions(+), 8 deletions(-)
> > 
> > diff --git a/Documentation/ABI/stable/sysfs-class-infiniband
> > b/Documentation/ABI/stable/sysfs-class-infiniband
> > index 694f23a03a28..e48a0d2fb4e5 100644
> > --- a/Documentation/ABI/stable/sysfs-class-infiniband
> > +++ b/Documentation/ABI/stable/sysfs-class-infiniband
> > @@ -157,8 +157,8 @@ Description:
> >  		all VLs from this port. This may include packets with errors.
> >  		This is 64 bit counter.
> >  
> > -		port_rcv_packets: (RO) Total number of packets (this may include
> > -		packets containing Errors. This is 64 bit counter.
> > +		port_rcv_packets: (RO) Total number of packets, this may include
> > +		packets containing Errors. This is a 64 bit counter.
> Comma doesn't feel like the right choice here.  Perhaps,
> 
> 		port_rc_packets: (RO) Total number of packets. May include
> 		packets containing Errors. This is a 64 bit counter.
> 
> Or just add the closing bracket.

will do this.

> >  
> >  		link_downed: (RO) Total number of times the Port Training state
> >  		machine has failed the link error recovery process and downed
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > index 28be1cabf112..108ea0abbdb6 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > @@ -16,7 +16,7 @@ Description:
> >  		In bridge applications, such as strain gauges and load cells,
> >  		the bridge itself consumes the majority of the current in the
> >  		system. To minimize the current consumption of the system,
> > -		the bridge can be disconnected (when it is not being used
> > +		the bridge can be disconnected when it is not being used
> >  		using the bridge_switch_en attribute.
> 
> I think intent would be better reflected here by adding the closing )
> That last bit is kind of a 'by the way' rather than the dominant point of
> the sentence.

		system. To minimize the current consumption of the system,
-		the bridge can be disconnected (when it is not being used
+		the bridge can be disconnected (when it is not being used)
 		using the bridge_switch_en attribute.
like this?

> 
> >  
> >  What:		/sys/bus/iio/devices/iio:deviceX/in_voltage2-voltage2_shorted_raw
> 
> > diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi
> > b/Documentation/ABI/testing/sysfs-firmware-gsmi
> > index 7a558354c1ee..88ca75d323d1 100644
> > --- a/Documentation/ABI/testing/sysfs-firmware-gsmi
> > +++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
> > @@ -18,7 +18,7 @@ Description:
> >  
> >  		/sys/firmware/gsmi/vars:
> >  
> > -			This directory has the same layout (and
> > +			This directory has the same layout and
> >  			underlying implementation as /sys/firmware/efi/vars.
> >  			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
> >  			for more information on how to interact with
> I think I'd add the bracket after implementation as this file is about ABI
> so that's less important than the rest of the sentence.

			This directory has the same layout (and
- 			underlying implementation as /sys/firmware/efi/vars.
+ 			underlying implementation) as /sys/firmware/efi/vars.
 			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
 			for more information on how to interact with

like this?

Thanks 
 manuel

Re: [PATCH] Documentation: ABI: fix brackets and bracelets

[Jonathan Cameron]

On Thu, 11 Jun 2026 13:54:04 +0200
Manuel Ebner <manuelebner@mailbox.org> wrote:

> On Thu, 2026-06-11 at 10:46 +0100, Jonathan Cameron wrote:
> > On Thu, 11 Jun 2026 10:56:21 +0200
> > Manuel Ebner <manuelebner@mailbox.org> wrote:
> >   
> > > Fix missing and needless brackets
> > > Fix missing bracelets
> > > 
> > > Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
> > > ---
> > >  Documentation/ABI/stable/sysfs-class-infiniband      | 4 ++--
> > >  Documentation/ABI/testing/sysfs-bus-iio              | 4 ++--
> > >  Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192   | 2 +-  
> > 
> > Take a look at hos this stuff is routed into upstream.  Each 
> > subsystem 'owns' their own documentation.  So this needs splitting up
> > on a per subsystem basis.  I'll also note that you've only +CC IIO folk
> > so you aren't going to get much review on the rest!  
> 
> I send it to the addresses get_maintainer returned, except the git blame
> ones. How can I find out who to send this to?

Some are easier to track down than others - look up related subsystems
in maintainers + look at anyone who has made significant changes to the files
in question.  However, some folk who work on Docs don't necessarily hang
around so also useful to use lore.kernel.org to see if they have been
on the list recently.  Also sometimes it is a bit fiddlier so look
at the original commits - that lets you find out what the files are associated
with.


INFINIBAND SUBSYSTEM
M:	Jason Gunthorpe <jgg@nvidia.com>
M:	Leon Romanovsky <leonro@nvidia.com>
L:	linux-rdma@vger.kernel.org

DMI/SMBIOS SUPPORT
M:	Jean Delvare <jdelvare@suse.com>
S:	Maintained

gsmi needed a bit of digging:
GOOGLE FIRMWARE DRIVERS
M:	Tzung-Bi Shih <tzungbi@kernel.org>
R:	Brian Norris <briannorris@chromium.org>
R:	Julius Werner <jwerner@chromium.org>
L:	chrome-platform@lists.linux.dev

Similar digging needed for sysfs-uevent, though I could probably have
guessed this one

DRIVER CORE, KOBJECTS, DEBUGFS AND SYSFS
M:	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
M:	"Rafael J. Wysocki" <rafael@kernel.org>
M:	Danilo Krummrich <dakr@kernel.org>
L:	driver-core@lists.linux.dev

IIO was the only one to have a specific match on these files.
It might be worth asking the other folk if they'd be happy to have
the MAINTAINERS entries updated to add one so that others find it easier
in future.

Jonathan

> 
> > A few comments inline.
> >   
> > >  Documentation/ABI/testing/sysfs-firmware-dmi-entries | 2 +-
> > >  Documentation/ABI/testing/sysfs-firmware-gsmi        | 2 +-
> > >  Documentation/ABI/testing/sysfs-uevent               | 2 +-
> > >  6 files changed, 8 insertions(+), 8 deletions(-)
> > > 
> > > diff --git a/Documentation/ABI/stable/sysfs-class-infiniband
> > > b/Documentation/ABI/stable/sysfs-class-infiniband
> > > index 694f23a03a28..e48a0d2fb4e5 100644
> > > --- a/Documentation/ABI/stable/sysfs-class-infiniband
> > > +++ b/Documentation/ABI/stable/sysfs-class-infiniband
> > > @@ -157,8 +157,8 @@ Description:
> > >  		all VLs from this port. This may include packets with errors.
> > >  		This is 64 bit counter.
> > >  
> > > -		port_rcv_packets: (RO) Total number of packets (this may include
> > > -		packets containing Errors. This is 64 bit counter.
> > > +		port_rcv_packets: (RO) Total number of packets, this may include
> > > +		packets containing Errors. This is a 64 bit counter.  
> > Comma doesn't feel like the right choice here.  Perhaps,
> > 
> > 		port_rc_packets: (RO) Total number of packets. May include
> > 		packets containing Errors. This is a 64 bit counter.
> > 
> > Or just add the closing bracket.  
> 
> will do this.
> 
> > >  
> > >  		link_downed: (RO) Total number of times the Port Training state
> > >  		machine has failed the link error recovery process and downed
> > > 
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > > b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > > index 28be1cabf112..108ea0abbdb6 100644
> > > --- a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > > @@ -16,7 +16,7 @@ Description:
> > >  		In bridge applications, such as strain gauges and load cells,
> > >  		the bridge itself consumes the majority of the current in the
> > >  		system. To minimize the current consumption of the system,
> > > -		the bridge can be disconnected (when it is not being used
> > > +		the bridge can be disconnected when it is not being used
> > >  		using the bridge_switch_en attribute.  
> > 
> > I think intent would be better reflected here by adding the closing )
> > That last bit is kind of a 'by the way' rather than the dominant point of
> > the sentence.  
> 
> 		system. To minimize the current consumption of the system,
> -		the bridge can be disconnected (when it is not being used
> +		the bridge can be disconnected (when it is not being used)
>  		using the bridge_switch_en attribute.
> like this?

Looks good.

> 
> >   
> > >  
> > >  What:		/sys/bus/iio/devices/iio:deviceX/in_voltage2-voltage2_shorted_raw  
> >   
> > > diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi
> > > b/Documentation/ABI/testing/sysfs-firmware-gsmi
> > > index 7a558354c1ee..88ca75d323d1 100644
> > > --- a/Documentation/ABI/testing/sysfs-firmware-gsmi
> > > +++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
> > > @@ -18,7 +18,7 @@ Description:
> > >  
> > >  		/sys/firmware/gsmi/vars:
> > >  
> > > -			This directory has the same layout (and
> > > +			This directory has the same layout and
> > >  			underlying implementation as /sys/firmware/efi/vars.
> > >  			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
> > >  			for more information on how to interact with  
> > I think I'd add the bracket after implementation as this file is about ABI
> > so that's less important than the rest of the sentence.  
> 
> 			This directory has the same layout (and
> - 			underlying implementation as /sys/firmware/efi/vars.
> + 			underlying implementation) as /sys/firmware/efi/vars.
>  			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
>  			for more information on how to interact with
> 
> like this?

yes

Thanks,

Jonathan

> 
> Thanks 
>  manuel

Re: [PATCH] Documentation: ABI: fix brackets and bracelets

[Andy Shevchenko]

On Thu, Jun 11, 2026 at 05:15:20PM +0100, Jonathan Cameron wrote:
> On Thu, 11 Jun 2026 13:54:04 +0200
> Manuel Ebner <manuelebner@mailbox.org> wrote:
> > On Thu, 2026-06-11 at 10:46 +0100, Jonathan Cameron wrote:
> > > On Thu, 11 Jun 2026 10:56:21 +0200
> > > Manuel Ebner <manuelebner@mailbox.org> wrote:

...

> > > Take a look at hos this stuff is routed into upstream.  Each 
> > > subsystem 'owns' their own documentation.  So this needs splitting up
> > > on a per subsystem basis.  I'll also note that you've only +CC IIO folk
> > > so you aren't going to get much review on the rest!  
> > 
> > I send it to the addresses get_maintainer returned, except the git blame
> > ones. How can I find out who to send this to?
> 
> Some are easier to track down than others - look up related subsystems
> in maintainers + look at anyone who has made significant changes to the files
> in question.  However, some folk who work on Docs don't necessarily hang
> around so also useful to use lore.kernel.org to see if they have been
> on the list recently.  Also sometimes it is a bit fiddlier so look
> at the original commits - that lets you find out what the files are associated
> with.

Also Cc Randy Dunlap, he is interested in documentation fixes.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH] Documentation: ABI: fix brackets and bracelets

[Andy Shevchenko]

On Thu, Jun 11, 2026 at 10:56:21AM +0200, Manuel Ebner wrote:
> Fix missing and needless brackets
> Fix missing bracelets

Please, use proper English punctuation.

...

>  		all VLs from this port. This may include packets with errors.
>  		This is 64 bit counter.

> +		port_rcv_packets: (RO) Total number of packets, this may include
> +		packets containing Errors. This is a 64 bit counter.

Side note: 64-bit (note a dash) is the standard form of telling the size of
the fixed-width values. Perhaps also update at some point?

...

> --- a/Documentation/ABI/testing/sysfs-firmware-dmi-entries
> +++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
> @@ -93,7 +93,7 @@ Description:
>  		  /sys/firmware/dmi/entries/15-0/system_event_log
>  
>  		and has the following attributes (documented in the
> -		SMBIOS / DMI specification under "System Event Log (Type 15)":
> +		SMBIOS / DMI specification under "System Event Log (Type 15)"):

Probably similar approach as in the rest?

		and has the following attributes, which is documented in the
		SMBIOS / DMI specification under "System Event Log (Type 15)":

>  		- area_length
>  		- header_start_offset

-- 
With Best Regards,
Andy Shevchenko