Skip to contentSkip to conversation

Additional doc warning fixes for issues at next-20200915

PATCH In review Mauro Carvalho Chehab 3 participants 6 messages Sep 17, 2020 – Sep 18, 2020

Subsystems (7)
lore
Share & tools
lore
#4 lore raw

PATCH 3/3 docs: bpf: ringbuf.rst: fix a broken cross-reference

In reply to Mauro Carvalho Chehab

Sphinx warns about a broken cross-reference:

Documentation/bpf/ringbuf.rst:194: WARNING: Unknown target name: "bench_ringbufs.c".

It seems that the original idea were to add a reference for this file:

tools/testing/selftests/bpf/benchs/bench_ringbufs.c

However, this won't work as such file is not part of the documentation output dir. It could be possible to use an extension like interSphinx in order to make external references to be pointed to some website (like kernel.org), where the file is stored, but currently we don't use it.

It would also be possible to include this file as a literal include, placing it inside Documentation/bpf.

For now, let's take the simplest approach: just drop the "_" markup at the end of the reference. This should solve the warning, and it sounds quite obvious that the file to see is at the Kernel tree.

---
 Documentation/bpf/ringbuf.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/bpf/ringbuf.rst +1 -1
index 4d4f3bcb1477..6a615cd62bda 100644
@@ -197,7 +197,7 @@ a self-pacing notifications of new data being availability.
 being available after commit only if consumer has already caught up right up to
 the record being committed. If not, consumer still has to catch up and thus
 will see new data anyways without needing an extra poll notification.
-Benchmarks (see tools/testing/selftests/bpf/benchs/bench_ringbufs.c_) show that
+Benchmarks (see tools/testing/selftests/bpf/benchs/bench_ringbufs.c) show that
 this allows to achieve a very high throughput without having to resort to
 tricks like "notify only every Nth sample", which are necessary with perf
 buffer. For extreme cases, when BPF program wants more manual control of
Signature · 1 line
2.26.2
#0 lore raw

cover Additional doc warning fixes for issues at next-20200915

There are a couple of new warnings introduced at linux-next.

This small patch series address them.

The complete series addressing (almost) all doc warnings is at:

https://git.linuxtv.org/mchehab/experimental.git/log/?h=doc-fixes

I'll keep rebasing such tree until we get rid of all doc warnings upstream, hopefully in time for Kernel 5.10.

Mauro Carvalho Chehab (3):
docs: kasan.rst: add two missing blank lines
mm: pagemap.h: fix two kernel-doc markups
docs: bpf: ringbuf.rst: fix a broken cross-reference

 Documentation/bpf/ringbuf.rst     | 2 +-
 Documentation/dev-tools/kasan.rst | 2 ++
 include/linux/pagemap.h           | 8 ++++----
 3 files changed, 7 insertions(+), 5 deletions(-)
Signature · 1 line
2.26.2
#1 lore raw

PATCH 1/3 docs: kasan.rst: add two missing blank lines

literal blocks should start and end with a blank line, as otherwise the parser complains and may do the wrong thing, as warned by Sphinx:

Documentation/dev-tools/kasan.rst:298: WARNING: Literal block ends without a blank line; unexpected unindent. Documentation/dev-tools/kasan.rst:303: WARNING: Literal block ends without a blank line; unexpected unindent.

---
 Documentation/dev-tools/kasan.rst | 2 ++
 1 file changed, 2 insertions(+)
Documentation/dev-tools/kasan.rst +2 -0
index c09c9ca2ff1c..2b68addaadcd 100644
@@ -295,11 +295,13 @@ print the number of the test and the status of the test:
 pass::
 
         ok 28 - kmalloc_double_kzfree
+
 or, if kmalloc failed::
 
         # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163
         Expected ptr is not null, but is
         not ok 4 - kmalloc_large_oob_right
+
 or, if a KASAN report was expected, but not found::
 
         # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629
Signature · 1 line
2.26.2
#3 lore raw

PATCH 2/3 mm: pagemap.h: fix two kernel-doc markups

In reply to Mauro Carvalho Chehab

Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the index parameter, but forgot to update the kernel-doc markups accordingly.

Fixes 6c8adf8446a3 ("mm: add find_lock_head")
---
 include/linux/pagemap.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
include/linux/pagemap.h +4 -4
index 4e52a3ff92fb..965ee92df1ad 100644
@@ -308,9 +308,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
 /**
  * find_lock_page - locate, pin and lock a pagecache page
  * @mapping: the address_space to search
- * @offset: the page index
+ * @index: the page index
  *
- * Looks up the page cache entry at @mapping & @offset.  If there is a
+ * Looks up the page cache entry at @mapping & @index.  If there is a
  * page cache page, it is returned locked and with an increased
  * refcount.
  *
@@ -327,9 +327,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
 /**
  * find_lock_head - Locate, pin and lock a pagecache page.
  * @mapping: The address_space to search.
- * @offset: The page index.
+ * @index: The page index.
  *
- * Looks up the page cache entry at @mapping & @offset.  If there is a
+ * Looks up the page cache entry at @mapping & @index.  If there is a
  * page cache page, its head page is returned locked and with an increased
  * refcount.
  *
Signature · 1 line
2.26.2
#5 lore raw

Re: [PATCH 3/3] docs: bpf: ringbuf.rst: fix a broken cross-reference

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

Sphinx warns about a broken cross-reference:

Documentation/bpf/ringbuf.rst:194: WARNING: Unknown target name: "bench_ringbufs.c".

It seems that the original idea were to add a reference for this file:

tools/testing/selftests/bpf/benchs/bench_ringbufs.c

However, this won't work as such file is not part of the documentation output dir. It could be possible to use an extension like interSphinx in order to make external references to be pointed to some website (like kernel.org), where the file is stored, but currently we don't use it.

It would also be possible to include this file as a literal include, placing it inside Documentation/bpf.

For now, let's take the simplest approach: just drop the "_" markup at the end of the reference. This should solve the warning, and it sounds quite obvious that the file to see is at the Kernel tree.

---
 Documentation/bpf/ringbuf.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/bpf/ringbuf.rst +0 -0
index 4d4f3bcb1477..6a615cd62bda 100644

Documentation/bpf/ringbuf.rst a self-pacing notifications of new data being availability. · line 200

Quoted 5 lines
Documentation/bpf/ringbuf.rst +1 -1
@@ -197,7 +197,7 @@ a self-pacing notifications of new data being availability.
 being available after commit only if consumer has already caught up right up to
 the record being committed. If not, consumer still has to catch up and thus
 will see new data anyways without needing an extra poll notification.
-Benchmarks (see tools/testing/selftests/bpf/benchs/bench_ringbufs.c_) show that
+Benchmarks (see tools/testing/selftests/bpf/benchs/bench_ringbufs.c) show that

This fix already landed in bpf and net trees.
Did you miss it?

Reviewed-by on v1 1/3
#2 lore raw

Re: [PATCH 1/3] docs: kasan.rst: add two missing blank lines

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

literal blocks should start and end with a blank line, as otherwise the parser complains and may do the wrong thing, as warned by Sphinx:

Documentation/dev-tools/kasan.rst:298: WARNING: Literal block ends without a blank line; unexpected unindent. Documentation/dev-tools/kasan.rst:303: WARNING: Literal block ends without a blank line; unexpected unindent.

---
 Documentation/dev-tools/kasan.rst | 2 ++
 1 file changed, 2 insertions(+)
Documentation/dev-tools/kasan.rst +0 -0
index c09c9ca2ff1c..2b68addaadcd 100644
@@ -295,11 +295,13 @@ print the number of the test and the status of the test:
 pass::
 
         ok 28 - kmalloc_double_kzfree

Documentation/dev-tools/kasan.rst print the number of the test and the status of the test: · line 307

Quoted 10 lines
Documentation/dev-tools/kasan.rst +2 -0
+
 or, if kmalloc failed::
 
         # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163
         Expected ptr is not null, but is
         not ok 4 - kmalloc_large_oob_right
+
 or, if a KASAN report was expected, but not found::
 
         # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629