[PATCH 0/3] Additional doc warning fixes for issues at next-20200915

[PATCH 0/3] Additional doc warning fixes for issues at next-20200915

[Mauro Carvalho Chehab]

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

-- 
2.26.2

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

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/bpf/ringbuf.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/bpf/ringbuf.rst b/Documentation/bpf/ringbuf.rst
index 4d4f3bcb1477..6a615cd62bda 100644
--- a/Documentation/bpf/ringbuf.rst
+++ b/Documentation/bpf/ringbuf.rst
@@ -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
-- 
2.26.2

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

[Alexei Starovoitov]

On Thu, Sep 17, 2020 at 1:04 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/bpf/ringbuf.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/bpf/ringbuf.rst b/Documentation/bpf/ringbuf.rst
> index 4d4f3bcb1477..6a615cd62bda 100644
> --- a/Documentation/bpf/ringbuf.rst
> +++ b/Documentation/bpf/ringbuf.rst
> @@ -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?