All of lore.kernel.org
 help / color / mirror / Atom feed
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
	Arnd Bergmann <arnd@arndb.de>, Jaroslav Kysela <perex@perex.cz>,
	Julia Lawall <Julia.Lawall@inria.fr>,
	Takashi Iwai <tiwai@suse.com>,
	alsa-devel@alsa-project.org, linux-kernel@vger.kernel.org
Subject: [PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
Date: Wed, 30 Sep 2020 15:25:02 +0200	[thread overview]
Message-ID: <9c68c182ae5aa978d68b64695b1e3292fcf58e76.1601467849.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1601467849.git.mchehab+huawei@kernel.org>

Some such markups are invalid, as reported by Sphinx:

	./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3317: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
	Invalid C declaration: Expected end of definition. [error at 20]
	  snd_rawmidi_transmit*
	  --------------------^
	./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3917: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
	Invalid C declaration: Expected end of definition. [error at 9]
	  copy_from/to_user
	  ---------^

The first case seems to be better replaced by a literal.

For the second one, let's generate cross-references, by
spliting it in two.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sound/kernel-api/writing-an-alsa-driver.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 85d6e9c643ef..73bbd59afc33 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -3315,8 +3315,7 @@ data and removes them from the buffer at once:
   }
 
 If you know beforehand how many bytes you can accept, you can use a
-buffer size greater than one with the
-:c:func:`snd_rawmidi_transmit\*()` functions.
+buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
 
 The ``trigger`` callback must not sleep. If the hardware FIFO is full
 before the substream buffer has been emptied, you have to continue
@@ -3916,7 +3915,7 @@ the maximum size of the proc file access.
 
 The read/write callbacks of raw mode are more direct than the text mode.
 You need to use a low-level I/O functions such as
-:c:func:`copy_from/to_user()` to transfer the data.
+:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
 
 ::
 
-- 
2.26.2


WARNING: multiple messages have this Message-ID (diff)
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>
Cc: alsa-devel@alsa-project.org, Arnd Bergmann <arnd@arndb.de>,
	Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
	linux-kernel@vger.kernel.org, Takashi Iwai <tiwai@suse.com>,
	Julia Lawall <Julia.Lawall@inria.fr>
Subject: [PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
Date: Wed, 30 Sep 2020 15:25:02 +0200	[thread overview]
Message-ID: <9c68c182ae5aa978d68b64695b1e3292fcf58e76.1601467849.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1601467849.git.mchehab+huawei@kernel.org>

Some such markups are invalid, as reported by Sphinx:

	./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3317: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
	Invalid C declaration: Expected end of definition. [error at 20]
	  snd_rawmidi_transmit*
	  --------------------^
	./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3917: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
	Invalid C declaration: Expected end of definition. [error at 9]
	  copy_from/to_user
	  ---------^

The first case seems to be better replaced by a literal.

For the second one, let's generate cross-references, by
spliting it in two.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sound/kernel-api/writing-an-alsa-driver.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 85d6e9c643ef..73bbd59afc33 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -3315,8 +3315,7 @@ data and removes them from the buffer at once:
   }
 
 If you know beforehand how many bytes you can accept, you can use a
-buffer size greater than one with the
-:c:func:`snd_rawmidi_transmit\*()` functions.
+buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
 
 The ``trigger`` callback must not sleep. If the hardware FIFO is full
 before the substream buffer has been emptied, you have to continue
@@ -3916,7 +3915,7 @@ the maximum size of the proc file access.
 
 The read/write callbacks of raw mode are more direct than the text mode.
 You need to use a low-level I/O functions such as
-:c:func:`copy_from/to_user()` to transfer the data.
+:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
 
 ::
 
-- 
2.26.2


  parent reply	other threads:[~2020-09-30 13:27 UTC|newest]

Thread overview: 103+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 03/52] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
2020-10-01 21:41   ` Jonathan Corbet
2020-10-01 23:02     ` Jonathan Corbet
2020-10-02  6:22     ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 05/52] scripts: kernel-doc: use a less pedantic markup for funcs on " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 06/52] scripts: kernel-doc: fix troubles with line counts Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 07/52] scripts: kernel-doc: reimplement -nofunction argument Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 08/52] scripts: kernel-doc: fix typedef identification Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 09/52] scripts: kernel-doc: don't mangle with parameter list Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 10/52] docs: kerneldoc.py: append the name of the parsed doc file Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 11/52] docs: kerneldoc.py: add support for kerneldoc -nosymbol Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 12/52] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 13/52] media: docs: make V4L documents more " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 14/52] media: docs: make DVB " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 15/52] media: docs: make MC " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 16/52] media: docs: make RC " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 17/52] media: cec-core.rst: don't use c:type for structs Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 18/52] math64.h: kernel-docs: Convert some markups into normal comments Mauro Carvalho Chehab
2020-09-30 13:46   ` Vincenzo Frascino
2020-09-30 13:24 ` [PATCH v4 19/52] memblock: get rid of a :c:type leftover Mauro Carvalho Chehab
2020-09-30 14:23   ` Mike Rapoport
2020-09-30 15:13     ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 20/52] drm: drm_dsc.h: fix a kernel-doc markup Mauro Carvalho Chehab
2020-09-30 13:24   ` Mauro Carvalho Chehab
2020-09-30 14:42   ` Daniel Vetter
2020-09-30 14:42     ` Daniel Vetter
2020-09-30 13:24 ` [PATCH v4 21/52] docs: remove some replace macros like |struct foo| Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs Mauro Carvalho Chehab
2020-09-30 13:24   ` Mauro Carvalho Chehab
2020-09-30 14:26   ` Mike Rapoport
2020-09-30 14:26     ` Mike Rapoport
2020-09-30 15:01   ` Takashi Iwai
2020-09-30 15:01     ` Takashi Iwai
2020-09-30 16:50   ` André Almeida
2020-09-30 16:50     ` André Almeida
2020-09-30 13:24 ` [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags Mauro Carvalho Chehab
2020-09-30 16:35   ` Steven Rostedt
2020-10-01  6:06   ` Kamalesh Babulal
2020-10-01  6:41     ` Mauro Carvalho Chehab
2020-10-01  8:27       ` Kamalesh Babulal
2020-09-30 13:24 ` [PATCH v4 24/52] docs: it_IT: fix namespace collisions at locking.rst Mauro Carvalho Chehab
2020-10-01 12:04   ` Federico Vaga
2020-09-30 13:24 ` [PATCH v4 25/52] docs: net: ieee802154.rst: fix C expressions Mauro Carvalho Chehab
2020-09-30 21:23   ` David Miller
2020-09-30 13:24 ` [PATCH v4 26/52] docs: genericirq.rst: don't document chip.c functions twice Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 27/52] docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 28/52] docs: remove sound API duplication Mauro Carvalho Chehab
2020-09-30 13:24   ` Mauro Carvalho Chehab
2020-09-30 14:57   ` Takashi Iwai
2020-09-30 14:57     ` Takashi Iwai
2020-09-30 13:24 ` [PATCH v4 29/52] docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 30/52] docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 31/52] docs: device_link.rst: remove duplicated kernel-doc include Mauro Carvalho Chehab
2020-09-30 21:03   ` Saravana Kannan
2020-09-30 13:24 ` [PATCH v4 32/52] docs: basics.rst: get rid of rcu kernel-doc macros Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc Mauro Carvalho Chehab
2020-09-30 21:23   ` David Miller
2020-09-30 13:24 ` [PATCH v4 34/52] docs: pstore-blk.rst: fix kernel-doc tags Mauro Carvalho Chehab
2020-09-30 23:23   ` Kees Cook
2020-09-30 13:24 ` [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags Mauro Carvalho Chehab
2020-09-30 16:21   ` Eric Biggers
2020-09-30 16:53     ` Mauro Carvalho Chehab
2020-09-30 17:06       ` Eric Biggers
2020-10-05 12:06         ` Mauro Carvalho Chehab
2020-10-05 19:08           ` Eric Biggers
2020-10-06  8:23             ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 36/52] docs: devices.rst: get rid of :c:type macros Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type Mauro Carvalho Chehab
2020-09-30 13:25   ` Mauro Carvalho Chehab
2020-09-30 14:59   ` Takashi Iwai
2020-09-30 14:59     ` Takashi Iwai
2020-09-30 13:25 ` [PATCH v4 38/52] docs: block: typec_bus.rst: " Mauro Carvalho Chehab
2020-09-30 16:48   ` André Almeida
2020-09-30 13:25 ` Mauro Carvalho Chehab [this message]
2020-09-30 13:25   ` [PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups Mauro Carvalho Chehab
2020-09-30 14:58   ` Takashi Iwai
2020-09-30 14:58     ` Takashi Iwai
2020-09-30 13:25 ` [PATCH v4 40/52] docs: fpga: replace :c:member: macros Mauro Carvalho Chehab
2020-09-30 23:46   ` Moritz Fischer
2020-09-30 13:25 ` [PATCH v4 41/52] docs: kgdb.rst: fix :c:type: usages Mauro Carvalho Chehab
2020-10-01 11:29   ` Daniel Thompson
2020-09-30 13:25 ` [PATCH v4 42/52] docs: libata.rst: fix a wrong usage of :c:type: tag Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 43/52] docs: infrastructure.rst: don't include firmware kernel-doc Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 44/52] docs: gpu: i915.rst: Fix several C duplication warnings Mauro Carvalho Chehab
2020-09-30 13:25   ` [Intel-gfx] " Mauro Carvalho Chehab
2020-09-30 13:25   ` Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 45/52] docs: devices.rst: fix a C reference markup Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 46/52] docs: it_IT: hacking.rst: fix a typo on a markup Mauro Carvalho Chehab
2020-10-01 12:05   ` Federico Vaga
2020-09-30 13:25 ` [PATCH v4 47/52] docs: mei.rst: fix a C expression markup Mauro Carvalho Chehab
2020-09-30 20:30   ` Winkler, Tomas
2020-09-30 13:25 ` [PATCH v4 48/52] docs: basics.rst: avoid duplicated C function declaration Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 49/52] workqueue: fix a kernel-doc warning Mauro Carvalho Chehab
2020-09-30 15:57   ` Tejun Heo
2020-09-30 13:25 ` [PATCH v4 50/52] scripts: kernel-doc: try to use c:function if possible Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 51/52] docs: conf.py: fix c:function support with Sphinx 3.x Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 52/52] docs: conf.py: change the Sphinx 3.x+ text Mauro Carvalho Chehab
2020-10-01 21:48 ` [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Jonathan Corbet
2020-10-02  6:52   ` Mauro Carvalho Chehab

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=9c68c182ae5aa978d68b64695b1e3292fcf58e76.1601467849.git.mchehab+huawei@kernel.org \
    --to=mchehab+huawei@kernel.org \
    --cc=Julia.Lawall@inria.fr \
    --cc=alsa-devel@alsa-project.org \
    --cc=arnd@arndb.de \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=perex@perex.cz \
    --cc=tiwai@suse.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.