Long story short, we need a space here for the reference to work
correctly.
Longer story:
Without the space, kerneldoc generates a line like this:
one of :c:type:`MemoryListener.region_add\(\) <MemoryListener>`,:c:type:`MemoryListener.region_del\(\)
Sphinx does not process the role information correctly, so we get this
(my pseudo-notation) construct:
<text>,:c:type:</text>
<reference target="MemoryListener">MemoryListener.region_del()</reference>
which does not reference the desired entity, and leaves some extra junk
in the rendered output. See
https://qemu-project.gitlab.io/qemu/devel/memory.html#c.MemoryListener
member log_start for an example of the broken output as it looks today.
Signed-off-by: John Snow <jsnow@redhat.com>
---
include/exec/memory.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/exec/memory.h b/include/exec/memory.h
index 5728a681b27..3b9ca696061 100644
--- a/include/exec/memory.h
+++ b/include/exec/memory.h
@@ -571,7 +571,7 @@ struct MemoryListener {
* @log_start:
*
* Called during an address space update transaction, after
- * one of #MemoryListener.region_add(),#MemoryListener.region_del() or
+ * one of #MemoryListener.region_add(), #MemoryListener.region_del() or
* #MemoryListener.region_nop(), if dirty memory logging clients have
* become active since the last transaction.
*
--
2.30.2
ping On 5/11/21 3:29 PM, John Snow wrote: > Long story short, we need a space here for the reference to work > correctly. > > > Longer story: > > Without the space, kerneldoc generates a line like this: > > one of :c:type:`MemoryListener.region_add\(\) <MemoryListener>`,:c:type:`MemoryListener.region_del\(\) > > Sphinx does not process the role information correctly, so we get this > (my pseudo-notation) construct: > > <text>,:c:type:</text> > <reference target="MemoryListener">MemoryListener.region_del()</reference> > > which does not reference the desired entity, and leaves some extra junk > in the rendered output. See > https://qemu-project.gitlab.io/qemu/devel/memory.html#c.MemoryListener > member log_start for an example of the broken output as it looks today. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > include/exec/memory.h | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/include/exec/memory.h b/include/exec/memory.h > index 5728a681b27..3b9ca696061 100644 > --- a/include/exec/memory.h > +++ b/include/exec/memory.h > @@ -571,7 +571,7 @@ struct MemoryListener { > * @log_start: > * > * Called during an address space update transaction, after > - * one of #MemoryListener.region_add(),#MemoryListener.region_del() or > + * one of #MemoryListener.region_add(), #MemoryListener.region_del() or > * #MemoryListener.region_nop(), if dirty memory logging clients have > * become active since the last transaction. > * >
On Tue, 11 May 2021 at 20:29, John Snow <jsnow@redhat.com> wrote: > > Long story short, we need a space here for the reference to work > correctly. > > > Longer story: > > Without the space, kerneldoc generates a line like this: > > one of :c:type:`MemoryListener.region_add\(\) <MemoryListener>`,:c:type:`MemoryListener.region_del\(\) > > Sphinx does not process the role information correctly, so we get this > (my pseudo-notation) construct: > > <text>,:c:type:</text> > <reference target="MemoryListener">MemoryListener.region_del()</reference> > > which does not reference the desired entity, and leaves some extra junk > in the rendered output. See > https://qemu-project.gitlab.io/qemu/devel/memory.html#c.MemoryListener > member log_start for an example of the broken output as it looks today. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > include/exec/memory.h | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/include/exec/memory.h b/include/exec/memory.h > index 5728a681b27..3b9ca696061 100644 > --- a/include/exec/memory.h > +++ b/include/exec/memory.h > @@ -571,7 +571,7 @@ struct MemoryListener { > * @log_start: > * > * Called during an address space update transaction, after > - * one of #MemoryListener.region_add(),#MemoryListener.region_del() or > + * one of #MemoryListener.region_add(), #MemoryListener.region_del() or > * #MemoryListener.region_nop(), if dirty memory logging clients have > * become active since the last transaction. > * > -- Reviewed-by: Peter Maydell <peter.maydell@linaro.org> thanks -- PMM
Le 11/05/2021 à 21:29, John Snow a écrit : > Long story short, we need a space here for the reference to work > correctly. > > > Longer story: > > Without the space, kerneldoc generates a line like this: > > one of :c:type:`MemoryListener.region_add\(\) <MemoryListener>`,:c:type:`MemoryListener.region_del\(\) > > Sphinx does not process the role information correctly, so we get this > (my pseudo-notation) construct: > > <text>,:c:type:</text> > <reference target="MemoryListener">MemoryListener.region_del()</reference> > > which does not reference the desired entity, and leaves some extra junk > in the rendered output. See > https://qemu-project.gitlab.io/qemu/devel/memory.html#c.MemoryListener > member log_start for an example of the broken output as it looks today. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > include/exec/memory.h | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/include/exec/memory.h b/include/exec/memory.h > index 5728a681b27..3b9ca696061 100644 > --- a/include/exec/memory.h > +++ b/include/exec/memory.h > @@ -571,7 +571,7 @@ struct MemoryListener { > * @log_start: > * > * Called during an address space update transaction, after > - * one of #MemoryListener.region_add(),#MemoryListener.region_del() or > + * one of #MemoryListener.region_add(), #MemoryListener.region_del() or > * #MemoryListener.region_nop(), if dirty memory logging clients have > * become active since the last transaction. > * > Applied to my trivial-patches branch. Thanks, Laurent
© 2016 - 2024 Red Hat, Inc.