[PATCH 0/9] Some doc fixes

[PATCH 0/9] Some doc fixes

[Mauro Carvalho Chehab]

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(-)

-- 
2.21.0

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

[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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 kernel/time/hrtimer.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
index edb230aba3d1..5ee77f1a8a92 100644
--- a/kernel/time/hrtimer.c
+++ b/kernel/time/hrtimer.c
@@ -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)
-- 
2.21.0

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

[Joe Perches]

On Fri, 2019-06-28 at 09:12 -0300, Mauro Carvalho Chehab wrote:
> 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.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  kernel/time/hrtimer.c | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
> index edb230aba3d1..5ee77f1a8a92 100644
> --- a/kernel/time/hrtimer.c
> +++ b/kernel/time/hrtimer.c
> @@ -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

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

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

[Mauro Carvalho Chehab]

Em Fri, 28 Jun 2019 05:39:25 -0700
Joe Perches <joe@perches.com> escreveu:

> On Fri, 2019-06-28 at 09:12 -0300, Mauro Carvalho Chehab wrote:
> > 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.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> >  kernel/time/hrtimer.c | 7 ++++---
> >  1 file changed, 4 insertions(+), 3 deletions(-)
> > 
> > diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
> > index edb230aba3d1..5ee77f1a8a92 100644
> > --- a/kernel/time/hrtimer.c
> > +++ b/kernel/time/hrtimer.c
> > @@ -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  
> 
> 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

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

[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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
---
 Documentation/trace/kprobetrace.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index fbb314bfa112..89ba487d4399 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -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
-- 
2.21.0

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

[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*`.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 kernel/signal.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/kernel/signal.c b/kernel/signal.c
index 91b789dd6e72..10a826855b59 100644
--- a/kernel/signal.c
+++ b/kernel/signal.c
@@ -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.
-- 
2.21.0

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

[Mauro Carvalho Chehab]

There's a typo there:
	ti_lmu.txt -> ti-lmu.txt

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Pavel Machek <pavel@ucw.cz>
Acked-by: Dan Murphy <dmurphy@ti.com>
---
 Documentation/devicetree/bindings/leds/leds-lm36274.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/leds/leds-lm36274.txt b/Documentation/devicetree/bindings/leds/leds-lm36274.txt
index 456a589c65f0..39c230d59a4d 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm36274.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm36274.txt
@@ -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
-- 
2.21.0

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

[Mauro Carvalho Chehab]

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

Fix them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Wolfram Sang <wsa@the-dreams.de>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 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(-)

diff --git a/Documentation/devicetree/bindings/arm/idle-states.txt b/Documentation/devicetree/bindings/arm/idle-states.txt
index 3bdbe675b9e6..d8d9aa7167e8 100644
--- a/Documentation/devicetree/bindings/arm/idle-states.txt
+++ b/Documentation/devicetree/bindings/arm/idle-states.txt
@@ -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
diff --git a/drivers/gpu/drm/i915/intel_runtime_pm.h b/drivers/gpu/drm/i915/intel_runtime_pm.h
index 473c4850c01d..2ee8f9522e05 100644
--- a/drivers/gpu/drm/i915/intel_runtime_pm.h
+++ b/drivers/gpu/drm/i915/intel_runtime_pm.h
@@ -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;
diff --git a/drivers/i2c/busses/i2c-nvidia-gpu.c b/drivers/i2c/busses/i2c-nvidia-gpu.c
index cfc76b5de726..5a1235fd86bb 100644
--- a/drivers/i2c/busses/i2c-nvidia-gpu.c
+++ b/drivers/i2c/busses/i2c-nvidia-gpu.c
@@ -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)
 {
-- 
2.21.0

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

[Mauro Carvalho Chehab]

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/virtual/kvm/amd-memory-encryption.rst | 2 ++
 Documentation/virtual/kvm/vcpu-requests.rst         | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/Documentation/virtual/kvm/amd-memory-encryption.rst b/Documentation/virtual/kvm/amd-memory-encryption.rst
index d18c97b4e140..6c37ff9a0a3c 100644
--- a/Documentation/virtual/kvm/amd-memory-encryption.rst
+++ b/Documentation/virtual/kvm/amd-memory-encryption.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ======================================
 Secure Encrypted Virtualization (SEV)
 ======================================
diff --git a/Documentation/virtual/kvm/vcpu-requests.rst b/Documentation/virtual/kvm/vcpu-requests.rst
index 5feb3706a7ae..c1807a1b92e6 100644
--- a/Documentation/virtual/kvm/vcpu-requests.rst
+++ b/Documentation/virtual/kvm/vcpu-requests.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================
 KVM VCPU Requests
 =================
-- 
2.21.0

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

[Mauro Carvalho Chehab]

This file is currently orphaned.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/gpu/drivers.rst        | 1 +
 Documentation/gpu/msm-crash-dump.rst | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index 4bfb7068e9f7..6c88c57b90cf 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -20,6 +20,7 @@ GPU Driver Documentation
    xen-front
    afbc
    komeda-kms
+   msm-crash-dump
 
 .. only::  subproject and html
 
diff --git a/Documentation/gpu/msm-crash-dump.rst b/Documentation/gpu/msm-crash-dump.rst
index 240ef200f76c..757cd257e0d8 100644
--- a/Documentation/gpu/msm-crash-dump.rst
+++ b/Documentation/gpu/msm-crash-dump.rst
@@ -1,5 +1,3 @@
-:orphan:
-
 =====================
 MSM Crash Dump Format
 =====================
-- 
2.21.0

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

[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")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 drivers/gpu/drm/drm_modes.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
index 57e6408288c8..4645af681ef8 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -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.
-- 
2.21.0

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

[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")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 drivers/platform/x86/Kconfig | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index bd15b47abcb4..c318501773bc 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -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

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

[Andy Shevchenko]

On Fri, Jun 28, 2019 at 3:12 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Changeset 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt")
> removed the x86-laptop-drivers.txt file, but forgot to update its
> Kconfig.

Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>

>
> Fixes: 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  drivers/platform/x86/Kconfig | 3 ---
>  1 file changed, 3 deletions(-)
>
> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> index bd15b47abcb4..c318501773bc 100644
> --- a/drivers/platform/x86/Kconfig
> +++ b/drivers/platform/x86/Kconfig
> @@ -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
>


-- 
With Best Regards,
Andy Shevchenko

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

[Jonathan Corbet]

On Fri, 28 Jun 2019 17:49:48 +0300
Andy Shevchenko <andy.shevchenko@gmail.com> wrote:

> On Fri, Jun 28, 2019 at 3:12 PM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > Changeset 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt")
> > removed the x86-laptop-drivers.txt file, but forgot to update its
> > Kconfig.  
> 
> Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>

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

jon