[PATCH 00/11] docs: fix build warning

[PATCH 00/11] docs: fix build warning

[Yanteng Si]

I can't stand these red warnings anymore, especially when I'm testing my
patches and looking for my own warnings in a sea of warnings. so, let's
fix them!

* Patch 0001 optimized the layout of the n_gsm.rst document, which would make the html rendering incorrect.

* Patch 0002-0011 Fix warning as:

linux-next/Documentation/admin-guide/device-mapper/writecache.rst:23: WARNING: Unexpected indentation.
linux-next/Documentation/arm64/tagged-address-abi.rst:52: WARNING: Unexpected indentation.
linux-next/Documentation/filesystems/netfs_library.rst:519: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/filesystems/netfs_library.rst:519: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/vm/page_owner.rst:92: WARNING: Unexpected indentation.
linux-next/Documentation/vm/page_owner.rst:96: WARNING: Unexpected indentation.
linux-next/Documentation/vm/page_owner.rst:107: WARNING: Unexpected indentation.
linux-next/Documentation/virt/kvm/api.rst:6046: WARNING: Literal block ends without a blank line; unexpected unindent.
linux-next/Documentation/virt/kvm/api.rst:7296: WARNING: Title underline too short.

8.28 KVM_CAP_ENFORCE_PV_FEATURE_CPUID
-----------------------------
linux-next/Documentation/virt/kvm/api.rst:7296: WARNING: Title underline too short.

8.28 KVM_CAP_ENFORCE_PV_FEATURE_CPUID
-----------------------------
linux-next/Documentation/driver-api/serial/n_gsm.rst:23: WARNING: Definition list ends without a blank line; unexpected unindent.
linux-next/Documentation/driver-api/serial/n_gsm.rst:100: WARNING: Definition list ends without a blank line; unexpected unindent.
linux-next/Documentation/driver-api/serial/n_gsm.rst:115: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:118: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:120: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:122: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:125: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:139: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/idr.rst:20: WARNING: Unknown target name: "xarray".
linux-next/Documentation/admin-guide/gpio/gpio-sim.rst: WARNING: 文档没有加入到任何目录树中
linux-next/Documentation/filesystems/caching/backend-api.rst:417: WARNING: undefined label: documentation/filesystems/netfs_library.rst (if the link has no caption the label must precede a section header)
linux-next/Documentation/trace/boottime-trace.rst:136: WARNING: undefined label: histogram (if the link has no caption the label must precede a section header)

* other:

<https://lore.kernel.org/linux-doc/20211205132141.4124145-1-siyanteng@loongson.cn/T/#u> Fix warning as:
linux-next/Documentation/networking/kapi:122: ./include/linux/phy.h:543: WARNING: Unexpected indentation.
linux-next/Documentation/networking/kapi:122: ./include/linux/phy.h:544: WARNING: Block quote ends without a blank line; unexpected unindent.
linux-next/Documentation/networking/kapi:122: ./include/linux/phy.h:546: WARNING: Unexpected indentation.

<https://lore.kernel.org/linux-doc/20211205131503.4122955-1-siyanteng@loongson.cn/T/#u> Fix warning as:
linux-next/Documentation/driver-api/regulator:166: ./include/linux/regulator/driver.h:96: WARNING: Unexpected indentation.
linux-next/Documentation/driver-api/regulator:166: ./include/linux/regulator/driver.h:98: WARNING: Block quote ends without a blank line; unexpected unindent.

<https://lore.kernel.org/linux-doc/20211205130816.4121898-1-siyanteng@loongson.cn/T/#u> Fix warning as:
linux-next/Documentation/driver-api/generic-counter:234: ./include/linux/counter.h:43: WARNING: Unexpected indentation.
linux-next/Documentation/driver-api/generic-counter:234: ./include/linux/counter.h:45: WARNING: Block quote ends without a blank line; unexpected unindent.

<https://lore.kernel.org/linux-doc/163a4dde20b8c4b68d668977a668e281d18fcf92.1638517064.git.siyanteng@loongson.cn/T/#u> Fix warning as:
linux-next/Documentation/scheduler/sched-bwc.rst:243: WARNING: Inline emphasis start-string without end-string.

* No fix:(These seem tricky,I can't do anything about it for now.)

linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:522: WARNING: Unexpected indentation.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:516: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:522: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:522: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:523: WARNING: Block quote ends without a blank line; unexpected unindent.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:526: WARNING: Definition list ends without a blank line; unexpected unindent.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:532: WARNING: Unexpected indentation.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:526: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:526: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:533: WARNING: Block quote ends without a blank line; unexpected unindent.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:542: WARNING: Unexpected indentation.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:535: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:535: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:542: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:542: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:544: WARNING: Block quote ends without a blank line; unexpected unindent.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:546: WARNING: Definition list ends without a blank line; unexpected unindent.
linux-next/Documentation/core-api/kernel-api:81: ./lib/bitmap.c:570: WARNING: Unexpected indentation.
linux-next/Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing:2: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/ABI/testing/sysfs-class-thermal:201: WARNING: Bullet list ends without a blank line; unexpected unindent.
linux-next/Documentation/networking/kapi:147: ./drivers/net/phy/phylink.c:1657: WARNING: Unexpected indentation.
linux-next/Documentation/networking/kapi:147: ./drivers/net/phy/phylink.c:1658: WARNING: Block quote ends without a blank line; unexpected unindent.
linux-next/Documentation/gpu/drm-kms-helpers:451: ./drivers/gpu/drm/drm_privacy_screen.c:270: WARNING: Inline emphasis start-string without end-string.



Yanteng Si (11):
  docs/driver-api: Reformatting serial ngsm
  docs/admin-guide: Add the necessary blank lines to the writecache
  docs/arm64: delete a space from tagged-address-abi
  docs/vm: delele three spaces from page_owner
  docs/filesystems: add four apostrophes to _start and _len
  docs/virt: add a blank line and some - to kvm api
  docs/driver-api: Replace a comma in the n_gsm.rst with a double colon
  docs/core-api: Replace Footnote Reference in document idr with
    Substitution Reference
  docs/filesystems: fix a label of backend-api
  docs/trace: fix a label of boottime-trace
  docs/admin-guide: add gpio-aggregator into index

 .../admin-guide/device-mapper/writecache.rst  |   1 +
 Documentation/admin-guide/gpio/index.rst      |   1 +
 Documentation/arm64/tagged-address-abi.rst    |   2 +-
 Documentation/core-api/idr.rst                |   3 +-
 Documentation/core-api/xarray.rst             |   1 -
 Documentation/driver-api/serial/n_gsm.rst     | 246 +++++++++---------
 .../filesystems/caching/backend-api.rst       |   2 +-
 Documentation/filesystems/netfs_library.rst   |   2 +-
 Documentation/trace/boottime-trace.rst        |   2 +-
 Documentation/virt/kvm/api.rst                |   3 +-
 Documentation/vm/page_owner.rst               |   6 +-
 11 files changed, 139 insertions(+), 130 deletions(-)

-- 
2.27.0

[PATCH 01/11] docs/driver-api: Reformatting serial ngsm

[Yanteng Si]

Added necessary indents and blank lines, optimized typography in html documents.eg:

 "1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. 1.4 obtain base gsmtty number for the used serial port."

Here's what they should have looked like:

 1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.

 1.4 obtain base gsmtty number for the used serial port.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/driver-api/serial/n_gsm.rst | 246 +++++++++++-----------
 1 file changed, 126 insertions(+), 120 deletions(-)

diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst
index 8fe723ab9c67..4fca5b16a0f3 100644
--- a/Documentation/driver-api/serial/n_gsm.rst
+++ b/Documentation/driver-api/serial/n_gsm.rst
@@ -15,130 +15,136 @@ How to use it
 1. config initiator
 ^^^^^^^^^^^^^^^^^^^^^
 
-1.1 initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
-    its serial port. Depending on the modem used, you can pass more or less
-    parameters to this command.
-1.2 switch the serial line to using the n_gsm line discipline by using
-    TIOCSETD ioctl.
-1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
-1.4 obtain base gsmtty number for the used serial port.
-
-Major parts of the initialization program :
-(a good starting point is util-linux-ng/sys-utils/ldattach.c)::
-
-  #include <stdio.h>
-  #include <stdint.h>
-  #include <linux/gsmmux.h>
-  #include <linux/tty.h>
-  #define DEFAULT_SPEED	B115200
-  #define SERIAL_PORT	/dev/ttyS0
-
-	int ldisc = N_GSM0710;
-	struct gsm_config c;
-	struct termios configuration;
-	uint32_t first;
-
-	/* open the serial port connected to the modem */
-	fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
-
-	/* configure the serial port : speed, flow control ... */
-
-	/* send the AT commands to switch the modem to CMUX mode
-	   and check that it's successful (should return OK) */
-	write(fd, "AT+CMUX=0\r", 10);
-
-	/* experience showed that some modems need some time before
-	   being able to answer to the first MUX packet so a delay
-	   may be needed here in some case */
-	sleep(3);
-
-	/* use n_gsm line discipline */
-	ioctl(fd, TIOCSETD, &ldisc);
-
-	/* get n_gsm configuration */
-	ioctl(fd, GSMIOC_GETCONF, &c);
-	/* we are initiator and need encoding 0 (basic) */
-	c.initiator = 1;
-	c.encapsulation = 0;
-	/* our modem defaults to a maximum size of 127 bytes */
-	c.mru = 127;
-	c.mtu = 127;
-	/* set the new configuration */
-	ioctl(fd, GSMIOC_SETCONF, &c);
-	/* get first gsmtty device node */
-	ioctl(fd, GSMIOC_GETFIRST, &first);
-	printf("first muxed line: /dev/gsmtty%i\n", first);
-
-	/* and wait for ever to keep the line discipline enabled */
-	daemon(0,0);
-	pause();
-
-1.5 use these devices as plain serial ports.
-
-   for example, it's possible:
-
-   - and to use gnokii to send / receive SMS on ttygsm1
-   - to use ppp to establish a datalink on ttygsm2
-
-1.6 first close all virtual ports before closing the physical port.
-
-   Note that after closing the physical port the modem is still in multiplexing
-   mode. This may prevent a successful re-opening of the port later. To avoid
-   this situation either reset the modem if your hardware allows that or send
-   a disconnect command frame manually before initializing the multiplexing mode
-   for the second time. The byte sequence for the disconnect command frame is::
-
-      0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9.
+  1.1 initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
+      its serial port. Depending on the modem used, you can pass more or less
+      parameters to this command.
+
+  1.2 switch the serial line to using the n_gsm line discipline by using
+      TIOCSETD ioctl.
+
+  1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
+
+  1.4 obtain base gsmtty number for the used serial port.
+
+  Major parts of the initialization program :
+  (a good starting point is util-linux-ng/sys-utils/ldattach.c)::
+
+    #include <stdio.h>
+    #include <stdint.h>
+    #include <linux/gsmmux.h>
+    #include <linux/tty.h>
+    #define DEFAULT_SPEED	B115200
+    #define SERIAL_PORT	/dev/ttyS0
+
+    int ldisc = N_GSM0710;
+    struct gsm_config c;
+    struct termios configuration;
+    uint32_t first;
+
+    /* open the serial port connected to the modem */
+    fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
+
+    /* configure the serial port : speed, flow control ... */
+
+    /* send the AT commands to switch the modem to CMUX mode
+       and check that it's successful (should return OK) */
+    write(fd, "AT+CMUX=0\r", 10);
+
+    /* experience showed that some modems need some time before
+       being able to answer to the first MUX packet so a delay
+       may be needed here in some case */
+    sleep(3);
+
+    /* use n_gsm line discipline */
+    ioctl(fd, TIOCSETD, &ldisc);
+
+    /* get n_gsm configuration */
+    ioctl(fd, GSMIOC_GETCONF, &c);
+    /* we are initiator and need encoding 0 (basic) */
+    c.initiator = 1;
+    c.encapsulation = 0;
+    /* our modem defaults to a maximum size of 127 bytes */
+    c.mru = 127;
+    c.mtu = 127;
+    /* set the new configuration */
+    ioctl(fd, GSMIOC_SETCONF, &c);
+    /* get first gsmtty device node */
+    ioctl(fd, GSMIOC_GETFIRST, &first);
+    printf("first muxed line: /dev/gsmtty%i\n", first);
+
+    /* and wait for ever to keep the line discipline enabled */
+    daemon(0,0);
+    pause();
+
+  1.5 use these devices as plain serial ports.
+
+     for example, it's possible:
+
+     - and to use gnokii to send / receive SMS on ttygsm1
+     - to use ppp to establish a datalink on ttygsm2
+
+  1.6 first close all virtual ports before closing the physical port.
+
+     Note that after closing the physical port the modem is still in multiplexing
+     mode. This may prevent a successful re-opening of the port later. To avoid
+     this situation either reset the modem if your hardware allows that or send
+     a disconnect command frame manually before initializing the multiplexing mode
+     for the second time. The byte sequence for the disconnect command frame is::
+
+        0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9.
 
 2. config requester
 ^^^^^^^^^^^^^^^^^^^^^
 
-2.1 receive string "AT+CMUX= command" through its serial port,initialize
-    mux mode config
-2.2 switch the serial line to using the n_gsm line discipline by using
-    TIOCSETD ioctl.
-2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
-2.4 obtain base gsmtty number for the used serial port,
-
-  #include <stdio.h>
-  #include <stdint.h>
-  #include <linux/gsmmux.h>
-  #include <linux/tty.h>
-  #define DEFAULT_SPEED	B115200
-  #define SERIAL_PORT	/dev/ttyS0
-
-	int ldisc = N_GSM0710;
-	struct gsm_config c;
-	struct termios configuration;
-	uint32_t first;
-
-	/* open the serial port */
-	fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
-
-	/* configure the serial port : speed, flow control ... */
-
-	/* get serial data and check "AT+CMUX=command" parameter ... */
-
-	/* use n_gsm line discipline */
-	ioctl(fd, TIOCSETD, &ldisc);
-
-	/* get n_gsm configuration */
-	ioctl(fd, GSMIOC_GETCONF, &c);
-	/* we are requester and need encoding 0 (basic) */
-	c.initiator = 0;
-	c.encapsulation = 0;
-	/* our modem defaults to a maximum size of 127 bytes */
-	c.mru = 127;
-	c.mtu = 127;
-	/* set the new configuration */
-	ioctl(fd, GSMIOC_SETCONF, &c);
-	/* get first gsmtty device node */
-	ioctl(fd, GSMIOC_GETFIRST, &first);
-	printf("first muxed line: /dev/gsmtty%i\n", first);
-
-	/* and wait for ever to keep the line discipline enabled */
-	daemon(0,0);
-	pause();
+  2.1 receive string "AT+CMUX= command" through its serial port,initialize
+      mux mode config.
+
+  2.2 switch the serial line to using the n_gsm line discipline by using
+      TIOCSETD ioctl.
+
+  2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
+
+  2.4 obtain base gsmtty number for the used serial port,
+
+    #include <stdio.h>
+    #include <stdint.h>
+    #include <linux/gsmmux.h>
+    #include <linux/tty.h>
+    #define DEFAULT_SPEED	B115200
+    #define SERIAL_PORT	/dev/ttyS0
+
+    int ldisc = N_GSM0710;
+    struct gsm_config c;
+    struct termios configuration;
+    uint32_t first;
+
+    /* open the serial port */
+    fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
+
+    /* configure the serial port : speed, flow control ... */
+
+    /* get serial data and check "AT+CMUX=command" parameter ... */
+
+    /* use n_gsm line discipline */
+    ioctl(fd, TIOCSETD, &ldisc);
+
+    /* get n_gsm configuration */
+    ioctl(fd, GSMIOC_GETCONF, &c);
+    /* we are requester and need encoding 0 (basic) */
+    c.initiator = 0;
+    c.encapsulation = 0;
+    /* our modem defaults to a maximum size of 127 bytes */
+    c.mru = 127;
+    c.mtu = 127;
+    /* set the new configuration */
+    ioctl(fd, GSMIOC_SETCONF, &c);
+    /* get first gsmtty device node */
+    ioctl(fd, GSMIOC_GETFIRST, &first);
+    printf("first muxed line: /dev/gsmtty%i\n", first);
+
+    /* and wait for ever to keep the line discipline enabled */
+    daemon(0,0);
+    pause();
 
 Additional Documentation
 ------------------------
-- 
2.27.0

Re: [PATCH 01/11] docs/driver-api: Reformatting serial ngsm

[Jonathan Corbet]

Yanteng Si <siyanteng01@gmail.com> writes:

> Added necessary indents and blank lines, optimized typography in html documents.eg:
>
>  "1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. 1.4 obtain base gsmtty number for the used serial port."
>
> Here's what they should have looked like:
>
>  1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
>
>  1.4 obtain base gsmtty number for the used serial port.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
>  Documentation/driver-api/serial/n_gsm.rst | 246 +++++++++++-----------
>  1 file changed, 126 insertions(+), 120 deletions(-)

So that is a huge diffstat for just having inserted some blank lines and
such.  What did you do that makes it appear that so many lines have been
changed?  What change in the code sample, for example?

Thanks,

jon

Re: [PATCH 01/11] docs/driver-api: Reformatting serial ngsm

[yanteng si]

Jonathan Corbet <corbet@lwn.net> 于2021年12月7日周二 01:56写道：
>
> Yanteng Si <siyanteng01@gmail.com> writes:
>
> > Added necessary indents and blank lines, optimized typography in html documents.eg:
> >
> >  "1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. 1.4 obtain base gsmtty number for the used serial port."
> >
> > Here's what they should have looked like:
> >
> >  1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
> >
> >  1.4 obtain base gsmtty number for the used serial port.
> >
> > Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > ---
> >  Documentation/driver-api/serial/n_gsm.rst | 246 +++++++++++-----------
> >  1 file changed, 126 insertions(+), 120 deletions(-)
>
> So that is a huge diffstat for just having inserted some blank lines and
> such.  What did you do that makes it appear that so many lines have been
> changed?  What change in the code sample, for example?
oops, I will fix it.

Thanks,
Yanteng

[PATCH 02/11] docs/admin-guide: Add the necessary blank lines to the writecache

[Yanteng Si]

Fix warning as:

  /home/siyanteng/linux-next/Documentation/admin-guide/device-mapper/writecache.rst:23: WARNING: Unexpected indentation.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/admin-guide/device-mapper/writecache.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/admin-guide/device-mapper/writecache.rst b/Documentation/admin-guide/device-mapper/writecache.rst
index 10429779a91a..6bf78b0446ac 100644
--- a/Documentation/admin-guide/device-mapper/writecache.rst
+++ b/Documentation/admin-guide/device-mapper/writecache.rst
@@ -20,6 +20,7 @@ Constructor parameters:
    size)
 5. the number of optional parameters (the parameters with an argument
    count as two)
+
 	start_sector n		(default: 0)
 		offset from the start of cache device in 512-byte sectors
 	high_watermark n	(default: 50)
-- 
2.27.0

[PATCH 03/11] docs/arm64: delete a space from tagged-address-abi

[Yanteng Si]

Fix warning as:

  linux-next/Documentation/arm64/tagged-address-abi.rst:52: WARNING: Unexpected indentation.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/arm64/tagged-address-abi.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arm64/tagged-address-abi.rst
index 0c9120ec58ae..540a1d4fc6c9 100644
--- a/Documentation/arm64/tagged-address-abi.rst
+++ b/Documentation/arm64/tagged-address-abi.rst
@@ -49,7 +49,7 @@ how the user addresses are used by the kernel:
 
    - ``brk()``, ``mmap()`` and the ``new_address`` argument to
      ``mremap()`` as these have the potential to alias with existing
-      user addresses.
+     user addresses.
 
      NOTE: This behaviour changed in v5.6 and so some earlier kernels may
      incorrectly accept valid tagged pointers for the ``brk()``,
-- 
2.27.0

[PATCH 04/11] docs/vm: delele three spaces from page_owner

[Yanteng Si]

Fix warning as:

linux-next/Documentation/vm/page_owner.rst:92: WARNING: Unexpected indentation.
linux-next/Documentation/vm/page_owner.rst:96: WARNING: Unexpected indentation.
linux-next/Documentation/vm/page_owner.rst:107: WARNING: Unexpected indentation.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/vm/page_owner.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
index 9837fc8147dd..9a3af6aafa09 100644
--- a/Documentation/vm/page_owner.rst
+++ b/Documentation/vm/page_owner.rst
@@ -89,11 +89,11 @@ Usage
 
 	Page allocated via order XXX, ...
 	PFN XXX ...
-	 // Detailed stack
+	// Detailed stack
 
 	Page allocated via order XXX, ...
 	PFN XXX ...
-	 // Detailed stack
+	// Detailed stack
 
    The ``page_owner_sort`` tool ignores ``PFN`` rows, puts the remaining rows
    in buf, uses regexp to extract the page order value, counts the times
@@ -104,7 +104,7 @@ Usage
 
 	XXX times, XXX pages:
 	Page allocated via order XXX, ...
-	 // Detailed stack
+	// Detailed stack
 
    By default, ``page_owner_sort`` is sorted according to the times of buf.
    If you want to sort by the pages nums of buf, use the ``-m`` parameter.
-- 
2.27.0

Re: [PATCH 04/11] docs/vm: delele three spaces from page_owner

[Jonathan Corbet]

Yanteng Si <siyanteng01@gmail.com> writes:

> Fix warning as:
>
> linux-next/Documentation/vm/page_owner.rst:92: WARNING: Unexpected indentation.
> linux-next/Documentation/vm/page_owner.rst:96: WARNING: Unexpected indentation.
> linux-next/Documentation/vm/page_owner.rst:107: WARNING: Unexpected indentation.

A general comment: "fixed a warning" is almost never a useful changelog
entry.  Instead, talk about what you fixed that was causing the warning;
that, not the warning itself, is the real problem.

> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
>  Documentation/vm/page_owner.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
> index 9837fc8147dd..9a3af6aafa09 100644
> --- a/Documentation/vm/page_owner.rst
> +++ b/Documentation/vm/page_owner.rst
> @@ -89,11 +89,11 @@ Usage
>  
>  	Page allocated via order XXX, ...
>  	PFN XXX ...
> -	 // Detailed stack
> +	// Detailed stack
>  
>  	Page allocated via order XXX, ...
>  	PFN XXX ...
> -	 // Detailed stack
> +	// Detailed stack

I don't think this is the right fix; instead, this text should be in a
literal block.

Thanks,

jon

Re: [PATCH 04/11] docs/vm: delele three spaces from page_owner

[yanteng si]

Jonathan Corbet <corbet@lwn.net> 于2021年12月7日周二 01:58写道：
>
> Yanteng Si <siyanteng01@gmail.com> writes:
>
> > Fix warning as:
> >
> > linux-next/Documentation/vm/page_owner.rst:92: WARNING: Unexpected indentation.
> > linux-next/Documentation/vm/page_owner.rst:96: WARNING: Unexpected indentation.
> > linux-next/Documentation/vm/page_owner.rst:107: WARNING: Unexpected indentation.
>
> A general comment: "fixed a warning" is almost never a useful changelog
> entry.  Instead, talk about what you fixed that was causing the warning;
> that, not the warning itself, is the real problem.
OK! get it.
>
> > Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > ---
> >  Documentation/vm/page_owner.rst | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> >
> > diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
> > index 9837fc8147dd..9a3af6aafa09 100644
> > --- a/Documentation/vm/page_owner.rst
> > +++ b/Documentation/vm/page_owner.rst
> > @@ -89,11 +89,11 @@ Usage
> >
> >       Page allocated via order XXX, ...
> >       PFN XXX ...
> > -      // Detailed stack
> > +     // Detailed stack
> >
> >       Page allocated via order XXX, ...
> >       PFN XXX ...
> > -      // Detailed stack
> > +     // Detailed stack
>
> I don't think this is the right fix; instead, this text should be in a
> literal block.
OK, Thanks!

Thanks,
Yanteng

[PATCH 05/11] docs/filesystems: add four apostrophes to _start and _len

[Yanteng Si]

Fix warning as:

linux-next/Documentation/filesystems/netfs_library.rst:519: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/filesystems/netfs_library.rst:519: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/filesystems/netfs_library.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst
index 732139d58e74..10d97b87de2a 100644
--- a/Documentation/filesystems/netfs_library.rst
+++ b/Documentation/filesystems/netfs_library.rst
@@ -518,7 +518,7 @@ The methods defined in the table are:
 
    [Required] Called to prepare a write to the cache to take place.  This
    involves checking to see whether the cache has sufficient space to honour
-   the write.  *_start and *_len indicate the region to be written; the region
+   the write.  ``*_start`` and ``*_len`` indicate the region to be written; the region
    can be shrunk or it can be expanded to a page boundary either way as
    necessary to align for direct I/O.  i_size holds the size of the object and
    is provided for reference.  no_space_allocated_yet is set to true if the
-- 
2.27.0

[PATCH 06/11] docs/virt: add a blank line and some - to kvm api

[Yanteng Si]

Fix warning as:

linux-next/Documentation/virt/kvm/api.rst:6046: WARNING: Literal block ends without a blank line; unexpected unindent.
linux-next/Documentation/virt/kvm/api.rst:7296: WARNING: Title underline too short.

8.28 KVM_CAP_ENFORCE_PV_FEATURE_CPUID
-----------------------------
linux-next/Documentation/virt/kvm/api.rst:7296: WARNING: Title underline too short.

8.28 KVM_CAP_ENFORCE_PV_FEATURE_CPUID
-----------------------------

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/virt/kvm/api.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index aeeb071c7688..a77c4533821f 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -6043,6 +6043,7 @@ Valid values for 'type' are:
 			unsigned long args[6];
 			unsigned long ret[2];
 		} riscv_sbi;
+
 If exit reason is KVM_EXIT_RISCV_SBI then it indicates that the VCPU has
 done a SBI call which is not handled by KVM RISC-V kernel module. The details
 of the SBI call are available in 'riscv_sbi' member of kvm_run structure. The
@@ -7293,7 +7294,7 @@ trap and emulate MSRs that are outside of the scope of KVM as well as
 limit the attack surface on KVM's MSR emulation code.
 
 8.28 KVM_CAP_ENFORCE_PV_FEATURE_CPUID
------------------------------
+-------------------------------------
 
 Architectures: x86
 
-- 
2.27.0

[PATCH 07/11] docs/driver-api: Replace a comma in the n_gsm.rst with a double colon

[Yanteng Si]

Fix warning as:

linux-next/Documentation/driver-api/serial/n_gsm.rst:23: WARNING: Definition list ends without a blank line; unexpected unindent.
linux-next/Documentation/driver-api/serial/n_gsm.rst:100: WARNING: Definition list ends without a blank line; unexpected unindent.
linux-next/Documentation/driver-api/serial/n_gsm.rst:115: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:118: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:120: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:122: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:125: WARNING: Inline emphasis start-string without end-string.
linux-next/Documentation/driver-api/serial/n_gsm.rst:139: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/driver-api/serial/n_gsm.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst
index 4fca5b16a0f3..90f222dc0d37 100644
--- a/Documentation/driver-api/serial/n_gsm.rst
+++ b/Documentation/driver-api/serial/n_gsm.rst
@@ -104,7 +104,7 @@ How to use it
 
   2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
 
-  2.4 obtain base gsmtty number for the used serial port,
+  2.4 obtain base gsmtty number for the used serial port::
 
     #include <stdio.h>
     #include <stdint.h>
-- 
2.27.0

[PATCH 08/11] docs/core-api: Replace Footnote Reference in document idr with Substitution Reference

[Yanteng Si]

Fix warning as:

linux-next/Documentation/core-api/idr.rst:20: WARNING: Unknown target name: "xarray".

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/core-api/idr.rst    | 3 ++-
 Documentation/core-api/xarray.rst | 1 -
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/core-api/idr.rst b/Documentation/core-api/idr.rst
index 3a1589b70244..be6023f42472 100644
--- a/Documentation/core-api/idr.rst
+++ b/Documentation/core-api/idr.rst
@@ -17,7 +17,8 @@ solution to the problem to avoid everybody inventing their own.  The IDR
 provides the ability to map an ID to a pointer, while the IDA provides
 only ID allocation, and as a result is much more memory-efficient.
 
-The IDR interface is deprecated; please use the XArray_ instead.
+The IDR interface is deprecated; please use the
+:XArray: Documentation/core-api/xarray.rst instead.
 
 IDR usage
 =========
diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst
index a91bc8aca5ab..a137a0e6d068 100644
--- a/Documentation/core-api/xarray.rst
+++ b/Documentation/core-api/xarray.rst
@@ -1,5 +1,4 @@
 .. SPDX-License-Identifier: GPL-2.0+
-.. _xarray:
 
 ======
 XArray
-- 
2.27.0

[PATCH 09/11] docs/filesystems: fix a label of backend-api

[Yanteng Si]

Fix warning as:

Documentation/filesystems/caching/backend-api.rst:417: WARNING: undefined label: documentation/filesystems/netfs_library.rst (if the link has no caption the label must precede a section header)

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/filesystems/caching/backend-api.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/filesystems/caching/backend-api.rst b/Documentation/filesystems/caching/backend-api.rst
index 72c3bbfe7ced..538be97bc1b4 100644
--- a/Documentation/filesystems/caching/backend-api.rst
+++ b/Documentation/filesystems/caching/backend-api.rst
@@ -414,7 +414,7 @@ A cache backend provides a data I/O API by through the netfs library's ``struct
 netfs_cache_ops`` attached to a ``struct netfs_cache_resources`` by the
 ``begin_operation`` method described above.
 
-See :ref:`Documentation/filesystems/netfs_library.rst` for a description.
+See :netfs_library: Documentation/filesystems/netfs_library.rst for a description.
 
 
 Miscellaneous Functions
-- 
2.27.0

[PATCH 10/11] docs/trace: fix a label of boottime-trace

[Yanteng Si]

Fix warning as:

Documentation/trace/boottime-trace.rst:136: WARNING: undefined label: histogram (if the link has no caption the label must precede a section header)

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/trace/boottime-trace.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
index 6dcfbc64014d..efb75ec5bf48 100644
--- a/Documentation/trace/boottime-trace.rst
+++ b/Documentation/trace/boottime-trace.rst
@@ -133,7 +133,7 @@ action option, there are tree-style options under per-event 'hist' subkey
 for the histogram actions. For the detail of the each parameter,
 please read the event histogram document [3]_.
 
-.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>`
+.. [3] See :histogram: Documentation/trace/histogram.rst
 
 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]]
   Set histogram key parameters. (Mandatory)
-- 
2.27.0

[PATCH 11/11] docs/admin-guide: add gpio-aggregator into index

[Yanteng Si]

Add gpio-aggregator into Documentation/admin-guide/gpio/index.rst

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 Documentation/admin-guide/gpio/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index 7db367572f30..f6861ca16ffe 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -10,6 +10,7 @@ gpio
     gpio-aggregator
     sysfs
     gpio-mockup
+    gpio-sim
 
 .. only::  subproject and html
 
-- 
2.27.0

Re: [PATCH 00/11] docs: fix build warning

[Jonathan Corbet]

Yanteng Si <siyanteng01@gmail.com> writes:

> I can't stand these red warnings anymore, especially when I'm testing my
> patches and looking for my own warnings in a sea of warnings. so, let's
> fix them!

So I totally approve of fixing docs build warnings, so thanks for doing
this work.  As I was working through the patches, though, I noticed that
these patches are against linux-next, so I can't take them into the docs
tree.  Instead, each fix needs to go into the tree that has introduced
the problem.

Thus, I encourage you to separate out this patch set, add an appropriate
Fixes tag to each, then send each separately to the same places where
the original patch went.  That should get these problems fixed before
they go into mainline.

Sorry to make more work, but I'd like to see these changes get in.  I've
commented on a couple of the individual patches as well.

Thanks,

jon

Re: [PATCH 00/11] docs: fix build warning

[yanteng si]

Jonathan Corbet <corbet@lwn.net> 于2021年12月7日周二 02:09写道：
>
> Yanteng Si <siyanteng01@gmail.com> writes:
>
> > I can't stand these red warnings anymore, especially when I'm testing my
> > patches and looking for my own warnings in a sea of warnings. so, let's
> > fix them!
>
> So I totally approve of fixing docs build warnings, so thanks for doing
> this work.  As I was working through the patches, though, I noticed that
> these patches are against linux-next, so I can't take them into the docs
> tree.  Instead, each fix needs to go into the tree that has introduced
> the problem.
>
> Thus, I encourage you to separate out this patch set, add an appropriate
> Fixes tag to each, then send each separately to the same places where
> the original patch went.  That should get these problems fixed before
> they go into mainline.
OK, will do!

Thanks,
Yanteng
>
> Sorry to make more work, but I'd like to see these changes get in.  I've
> commented on a couple of the individual patches as well.
>
> Thanks,
>
> jon