Skip to contentSkip to conversation

Some doc fixes

PATCH In review Mauro Carvalho Chehab 4 participants 14 messages Jun 28, 2019

Subsystems (12)
lore
Share & tools
lore
#0 lore raw

cover Some doc fixes

This patch series is against linux-next (next-20190627). I doubt those would apply cleanly against docs next tree.

So, please apply it via the subsystem trees. Otherwise, they could be pushed by the end of the merge window or for -rc1 via a docs tree.

Most, if not all were I already sent.

Mauro Carvalho Chehab (9):
hrtimer: Use a bullet for the returns bullet list
docs: trace: fix a broken label
docs: signal: fix a kernel-doc markup
dt: leds-lm36274.txt: fix a broken reference to ti-lmu.txt
docs: fix some broken references due to txt->rst renames
docs: virtual: there are two orphan docs there
docs: gpu: add msm-crash-dump.rst to the index.rst file
drm: fix a reference for a renamed file: fb/modedb.rst
platform: x86: get rid of a non-existent document

 Documentation/devicetree/bindings/arm/idle-states.txt   | 2 +-
 Documentation/devicetree/bindings/leds/leds-lm36274.txt | 2 +-
 Documentation/gpu/drivers.rst                           | 1 +
 Documentation/gpu/msm-crash-dump.rst                    | 2 --
 Documentation/trace/kprobetrace.rst                     | 1 +
 Documentation/virtual/kvm/amd-memory-encryption.rst     | 2 ++
 Documentation/virtual/kvm/vcpu-requests.rst             | 2 ++
 drivers/gpu/drm/drm_modes.c                             | 2 +-
 drivers/gpu/drm/i915/intel_runtime_pm.h                 | 2 +-
 drivers/i2c/busses/i2c-nvidia-gpu.c                     | 2 +-
 drivers/platform/x86/Kconfig                            | 3 ---
 kernel/signal.c                                         | 2 +-
 kernel/time/hrtimer.c                                   | 7 ++++---
 13 files changed, 16 insertions(+), 14 deletions(-)
Signature · 7 lines
2.21.0


_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#6 lore raw

PATCH 4/9 dt: leds-lm36274.txt: fix a broken reference to ti-lmu.txt

There's a typo there:

	ti_lmu.txt -> ti-lmu.txt
---
 Documentation/devicetree/bindings/leds/leds-lm36274.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/devicetree/bindings/leds/leds-lm36274.txt +1 -1
index 456a589c65f0..39c230d59a4d 100644
@@ -6,7 +6,7 @@ up to 29V total output voltage. The 11-bit LED current is programmable via
 the I2C bus and/or controlled via a logic level PWM input from 60 uA to 30 mA.
 
 Parent device properties are documented in
-Documentation/devicetree/bindings/mfd/ti_lmu.txt
+Documentation/devicetree/bindings/mfd/ti-lmu.txt
 
 Regulator properties are documented in
 Documentation/devicetree/bindings/regulator/lm363x-regulator.txt
Signature · 1 line
2.21.0
#7 lore raw

PATCH 5/9 docs: fix some broken references due to txt->rst renames

In reply to Mauro Carvalho Chehab

There are three left-overs from the recent file renames, probably due to some other conflicting patch.

Fix them.

---
 Documentation/devicetree/bindings/arm/idle-states.txt | 2 +-
 drivers/gpu/drm/i915/intel_runtime_pm.h               | 2 +-
 drivers/i2c/busses/i2c-nvidia-gpu.c                   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
Documentation/devicetree/bindings/arm/idle-states.txt +1 -1
index 3bdbe675b9e6..d8d9aa7167e8 100644
@@ -703,4 +703,4 @@ cpus {
     https://www.devicetree.org/specifications/
 
 [6] ARM Linux Kernel documentation - Booting AArch64 Linux
-    Documentation/arm64/booting.txt
+    Documentation/arm64/booting.rst
drivers/gpu/drm/i915/intel_runtime_pm.h +1 -1
index 473c4850c01d..2ee8f9522e05 100644
@@ -45,7 +45,7 @@ enum i915_drm_suspend_mode {
  * to be disabled. This shouldn't happen and we'll print some error messages in
  * case it happens.
  *
- * For more, read the Documentation/power/runtime_pm.txt.
+ * For more, read the Documentation/power/runtime_pm.rst.
  */
 struct intel_runtime_pm {
 	atomic_t wakeref_count;
drivers/i2c/busses/i2c-nvidia-gpu.c +1 -1
index cfc76b5de726..5a1235fd86bb 100644
@@ -364,7 +364,7 @@ static void gpu_i2c_remove(struct pci_dev *pdev)
 /*
  * We need gpu_i2c_suspend() even if it is stub, for runtime pm to work
  * correctly. Without it, lspci shows runtime pm status as "D0" for the card.
- * Documentation/power/pci.txt also insists for driver to provide this.
+ * Documentation/power/pci.rst also insists for driver to provide this.
  */
 static __maybe_unused int gpu_i2c_suspend(struct device *dev)
 {
Signature · 6 lines
2.21.0

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#11 lore raw

PATCH 9/9 platform: x86: get rid of a non-existent document

In reply to Mauro Carvalho Chehab

Changeset 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt") removed the x86-laptop-drivers.txt file, but forgot to update its Kconfig.

Fixes 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt")
---
 drivers/platform/x86/Kconfig | 3 ---
 1 file changed, 3 deletions(-)
drivers/platform/x86/Kconfig +0 -3
index bd15b47abcb4..c318501773bc 100644
@@ -433,9 +433,6 @@ config COMPAL_LAPTOP
 	  It adds support for rfkill, Bluetooth, WLAN, LCD brightness, hwmon
 	  and battery charging level control.
 
-	  For a (possibly incomplete) list of supported laptops, please refer
-	  to: Documentation/platform/x86-laptop-drivers.txt
-
 config SONY_LAPTOP
 	tristate "Sony Laptop Extras"
 	depends on ACPI
Signature · 1 line
2.21.0
#5 lore raw

PATCH 3/9 docs: signal: fix a kernel-doc markup

In reply to Mauro Carvalho Chehab

The kernel-doc parser doesn't handle expressions with %foo*. Instead, when an asterisk should be part of a constant, it uses an alternative notation: foo*.

---
 kernel/signal.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
kernel/signal.c +1 -1
index 91b789dd6e72..10a826855b59 100644
@@ -349,7 +349,7 @@ void task_clear_jobctl_pending(struct task_struct *task, unsigned long mask)
  * @task has %JOBCTL_STOP_PENDING set and is participating in a group stop.
  * Group stop states are cleared and the group stop count is consumed if
  * %JOBCTL_STOP_CONSUME was set.  If the consumption completes the group
- * stop, the appropriate %SIGNAL_* flags are set.
+ * stop, the appropriate `SIGNAL_*` flags are set.
  *
  * CONTEXT:
  * Must be called with @task->sighand->siglock held.
Signature · 1 line
2.21.0
#9 lore raw

PATCH 7/9 docs: gpu: add msm-crash-dump.rst to the index.rst file

In reply to Mauro Carvalho Chehab

This file is currently orphaned.

---
 Documentation/gpu/drivers.rst        | 1 +
 Documentation/gpu/msm-crash-dump.rst | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)
Documentation/gpu/drivers.rst +1 -0
index 4bfb7068e9f7..6c88c57b90cf 100644
@@ -20,6 +20,7 @@ GPU Driver Documentation
    xen-front
    afbc
    komeda-kms
+   msm-crash-dump
 
 .. only::  subproject and html
 
Documentation/gpu/msm-crash-dump.rst +0 -2
index 240ef200f76c..757cd257e0d8 100644
@@ -1,5 +1,3 @@
-:orphan:
-
 =====================
 MSM Crash Dump Format
 =====================
Signature · 6 lines
2.21.0

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#10 lore raw

PATCH 8/9 drm: fix a reference for a renamed file: fb/modedb.rst

In reply to Mauro Carvalho Chehab

Due to two patches being applied about the same time, the reference for modedb.rst file got wrong:

Documentation/fb/modedb.txt is now Documentation/fb/modedb.rst.

Fixes 1bf4e09227c3 ("drm/modes: Allow to specify rotation and reflection on the commandline")
Fixes ab42b818954c ("docs: fb: convert docs to ReST and rename to *.rst")
---
 drivers/gpu/drm/drm_modes.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_modes.c +1 -1
index 57e6408288c8..4645af681ef8 100644
@@ -1680,7 +1680,7 @@ static int drm_mode_parse_cmdline_options(char *str, size_t len,
  *
  * Additionals options can be provided following the mode, using a comma to
  * separate each option. Valid options can be found in
- * Documentation/fb/modedb.txt.
+ * Documentation/fb/modedb.rst.
  *
  * The intermediate drm_cmdline_mode structure is required to store additional
  * options from the command line modline like the force-enable/disable flag.
Signature · 6 lines
2.21.0

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#8 lore raw

PATCH 6/9 docs: virtual: there are two orphan docs there

In reply to Mauro Carvalho Chehab
---
 Documentation/virtual/kvm/amd-memory-encryption.rst | 2 ++
 Documentation/virtual/kvm/vcpu-requests.rst         | 2 ++
 2 files changed, 4 insertions(+)
Documentation/virtual/kvm/amd-memory-encryption.rst +2 -0
index d18c97b4e140..6c37ff9a0a3c 100644
@@ -1,3 +1,5 @@
+:orphan:
+
 ======================================
 Secure Encrypted Virtualization (SEV)
 ======================================
Documentation/virtual/kvm/vcpu-requests.rst +2 -0
index 5feb3706a7ae..c1807a1b92e6 100644
@@ -1,3 +1,5 @@
+:orphan:
+
 =================
 KVM VCPU Requests
 =================
Signature · 1 line
2.21.0
#1 lore raw

PATCH 1/9 hrtimer: Use a bullet for the returns bullet list

In reply to Mauro Carvalho Chehab

That gets rid of this warning:

./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.

and displays nicely both at the source code and at the produced documentation.

---
 kernel/time/hrtimer.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
kernel/time/hrtimer.c +4 -3
index edb230aba3d1..5ee77f1a8a92 100644
@@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
  * @timer:	hrtimer to stop
  *
  * Returns:
- *  0 when the timer was not active
- *  1 when the timer was active
- * -1 when the timer is currently executing the callback function and
+ *
+ *  *  0 when the timer was not active
+ *  *  1 when the timer was active
+ *  * -1 when the timer is currently executing the callback function and
  *    cannot be stopped
  */
 int hrtimer_try_to_cancel(struct hrtimer *timer)
Signature · 1 line
2.21.0
#4 lore raw

PATCH 2/9 docs: trace: fix a broken label

In reply to Mauro Carvalho Chehab

Sphinx warnings about his:

Documentation/trace/kprobetrace.rst:68: WARNING: undefined label: user_mem_access (if the link has no caption the label must precede a section header)

The problem is quite simple: Sphinx wants a blank line after references.

---
 Documentation/trace/kprobetrace.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/trace/kprobetrace.rst +1 -0
index fbb314bfa112..89ba487d4399 100644
@@ -96,6 +96,7 @@ which shows given pointer in "symbol+offset" style.
 For $comm, the default type is "string"; any other type is invalid.
 
 .. _user_mem_access:
+
 User Memory Access
 ------------------
 Kprobe events supports user-space memory access. For that purpose, you can use
Signature · 1 line
2.21.0
#2 lore raw

Re: [PATCH 1/9] hrtimer: Use a bullet for the returns bullet list

In reply to Mauro Carvalho Chehab
Quoted 18 lines · Mauro Carvalho Chehab

That gets rid of this warning:

./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.

and displays nicely both at the source code and at the produced documentation.

---
 kernel/time/hrtimer.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
kernel/time/hrtimer.c +0 -0
index edb230aba3d1..5ee77f1a8a92 100644
@@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
  * @timer:	hrtimer to stop

kernel/time/hrtimer.c EXPORT_SYMBOL_GPL(hrtimer_start_range_ns); · line 1121

Quoted 10 lines
kernel/time/hrtimer.c +4 -3
  *
  * Returns:
- *  0 when the timer was not active
- *  1 when the timer was active
- * -1 when the timer is currently executing the callback function and
+ *
+ *  *  0 when the timer was not active
+ *  *  1 when the timer was active
+ *  * -1 when the timer is currently executing the callback function and
  *    cannot be stopped

I think this last line should be indented 3 more spaces too

#3 lore raw

Re: [PATCH 1/9] hrtimer: Use a bullet for the returns bullet list

Em Fri, 28 Jun 2019 05:39:25 -0700
Joe Perches <[email protected]> escreveu:

Quoted 23 lines · Mauro Carvalho Chehab
Quoted 22 lines

That gets rid of this warning:

./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.

and displays nicely both at the source code and at the produced documentation.

---
 kernel/time/hrtimer.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
kernel/time/hrtimer.c +0 -2
index edb230aba3d1..5ee77f1a8a92 100644
@@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
  * @timer:	hrtimer to stop
  *
  * Returns:
- *  0 when the timer was not active
- *  1 when the timer was active
Quoted 8 lines

kernel/time/hrtimer.c EXPORT_SYMBOL_GPL(hrtimer_start_range_ns); · line 1121

Quoted 6 lines
kernel/time/hrtimer.c +4 -1
- * -1 when the timer is currently executing the callback function and
+ *
+ *  *  0 when the timer was not active
+ *  *  1 when the timer was active
+ *  * -1 when the timer is currently executing the callback function and
  *    cannot be stopped  

I think this last line should be indented 3 more spaces too

That would produce a warning, and will change the font for the content of the first line to bold.

ReST is pedantic with whitespaces, as it uses it to identify continuation lines.

For it to consider one line as a continuation of the previous one, the texts on both lines (after markups) should start at the same place.

So, on:

* foo
bar

"bar" is considered a continuation of the first line. So, identical to:

* foo bar

But:

* foo bar
foobar

the whitespace doesn't match. it will change the font for the first line to bold, and place foobar on a separate line.

(yeah, I know that, for kernel-doc, this sucks)

Thanks,
Mauro

Acked-by on v1 9/9
#12 lore raw

Re: [PATCH 9/9] platform: x86: get rid of a non-existent document

In reply to Mauro Carvalho Chehab
Quoted 4 lines · Mauro Carvalho Chehab

Changeset 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt") removed the x86-laptop-drivers.txt file, but forgot to update its Kconfig.

Quoted 24 lines
Fixes 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt")
---
 drivers/platform/x86/Kconfig | 3 ---
 1 file changed, 3 deletions(-)
drivers/platform/x86/Kconfig +0 -4
index bd15b47abcb4..c318501773bc 100644
@@ -433,9 +433,6 @@ config COMPAL_LAPTOP
          It adds support for rfkill, Bluetooth, WLAN, LCD brightness, hwmon
          and battery charging level control.
 
-         For a (possibly incomplete) list of supported laptops, please refer
-         to: Documentation/platform/x86-laptop-drivers.txt
-
 config SONY_LAPTOP
        tristate "Sony Laptop Extras"
        depends on ACPI
--

2.21.0

Signature · 2 lines
With Best Regards,
Andy Shevchenko
maintainer
#13 lore raw

Re: [PATCH 9/9] platform: x86: get rid of a non-existent document

Quoted 8 lines · On Fri, 28 Jun 2019 17:49:48 +0300 Andy Shevchenko <[email protected]>…
Quoted 4 lines · Mauro Carvalho Chehab

Changeset 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt") removed the x86-laptop-drivers.txt file, but forgot to update its Kconfig.

The patch that brought this situation into being is in docs-next, so I applied this one too.

jon