linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: unlisted-recipients:; (no To-header on input)
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	linux-doc@vger.kernel.org
Subject: [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings
Date: Tue,  3 Mar 2020 16:50:32 +0100	[thread overview]
Message-ID: <637fc605eb2fe6e27d9983ee5c30d78989618313.1583250595.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <afbe367ccb7b9abcb9fab7bc5cb5e0686c105a53.1583250595.git.mchehab+huawei@kernel.org>

Sphinx doesn't like multi-line literal blocks with ``foobar``:

    Documentation/watch_queue.rst:109: WARNING: Inline literal start-string without end-string.
    Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
    Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
    Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
    Documentation/watch_queue.rst:186: WARNING: Inline literal start-string without end-string.
    Documentation/watch_queue.rst:186: WARNING: Inline emphasis start-string without end-string.
    Documentation/watch_queue.rst:185: WARNING: Inline emphasis start-string without end-string.

So, let's use the "::" markup instead.

While we could do the fix only at the affected lines, let's
do the same change along the entire file, in order to preserve
the same look and feel at the entire doc.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/watch_queue.rst | 34 +++++++++++++++++++++++++---------
 1 file changed, 25 insertions(+), 9 deletions(-)

diff --git a/Documentation/watch_queue.rst b/Documentation/watch_queue.rst
index d8f70282d247..f1ffe9cdf81f 100644
--- a/Documentation/watch_queue.rst
+++ b/Documentation/watch_queue.rst
@@ -105,15 +105,19 @@ watch that specific key).
 
 To manage a watch list, the following functions are provided:
 
-  * ``void init_watch_list(struct watch_list *wlist,
-			   void (*release_watch)(struct watch *wlist));``
+  * ::
+
+      void init_watch_list(struct watch_list *wlist,
+			   void (*release_watch)(struct watch *wlist));
 
     Initialise a watch list.  If ``release_watch`` is not NULL, then this
     indicates a function that should be called when the watch_list object is
     destroyed to discard any references the watch list holds on the watched
     object.
 
-  * ``void remove_watch_list(struct watch_list *wlist);``
+  * ::
+
+      void remove_watch_list(struct watch_list *wlist);
 
     This removes all of the watches subscribed to a watch_list and frees them
     and then destroys the watch_list object itself.
@@ -127,14 +131,18 @@ records will be written into.  The workings of this are hidden entirely inside
 of the watch_queue device driver, but it is necessary to gain a reference to it
 to set a watch.  These can be managed with:
 
-  * ``struct watch_queue *get_watch_queue(int fd);``
+  * ::
+
+      struct watch_queue *get_watch_queue(int fd);``
 
     Since watch queues are indicated to the kernel by the fd of the pipe that
     implements the buffer, userspace must hand that fd through a system call.
     This can be used to look up an opaque pointer to the watch queue from the
     system call.
 
-  * ``void put_watch_queue(struct watch_queue *wqueue);``
+  * ::
+
+      void put_watch_queue(struct watch_queue *wqueue);
 
     This discards the reference obtained from ``get_watch_queue()``.
 
@@ -170,18 +178,24 @@ different ID are ignored.
 
 The following functions are provided to manage watches:
 
-  * ``void init_watch(struct watch *watch, struct watch_queue *wqueue);``
+  * ::
+
+      void init_watch(struct watch *watch, struct watch_queue *wqueue);
 
     Initialise a watch object, setting its pointer to the watch queue, using
     appropriate barriering to avoid lockdep complaints.
 
-  * ``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);``
+  * ::
+
+      int add_watch_to_object(struct watch *watch, struct watch_list *wlist);
 
     Subscribe a watch to a watch list (notification source).  The
     driver-settable fields in the watch struct must have been set before this
     is called.
 
-  * ``int remove_watch_from_object(struct watch_list *wlist,
+  * ::
+
+      int remove_watch_from_object(struct watch_list *wlist,
 				   struct watch_queue *wqueue,
 				   u64 id, false);``
 
@@ -190,7 +204,9 @@ The following functions are provided to manage watches:
     (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue to
     indicate that the watch got removed.
 
-  * ``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);``
+  * ::
+
+      int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);
 
     Remove all the watches from a watch list.  It is expected that this will be
     called preparatory to destruction and that the watch list will be
-- 
2.24.1


  reply	other threads:[~2020-03-03 15:50 UTC|newest]

Thread overview: 24+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-03-03 15:50 [PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format Mauro Carvalho Chehab
2020-03-03 15:50 ` Mauro Carvalho Chehab [this message]
2020-03-10 17:53   ` [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings Jonathan Corbet
2020-03-10 18:29   ` David Howells
2020-03-11 12:11     ` Mauro Carvalho Chehab
2020-03-03 15:50 ` [PATCH 3/9] docs: dmaengine: provider.rst: get rid of some warnings Mauro Carvalho Chehab
2020-03-06 13:39   ` Vinod Koul
2020-03-03 15:50 ` [PATCH 4/9] docs: driver.rst: supress two ReSt warnings Mauro Carvalho Chehab
2020-03-10 17:54   ` Jonathan Corbet
2020-03-03 15:50 ` [PATCH 5/9] docs: gpio: driver.rst: don't mark literal blocks twice Mauro Carvalho Chehab
2020-03-04 14:20   ` Bartosz Golaszewski
2020-03-03 15:50 ` [PATCH 6/9] docs: translations: it: avoid duplicate refs at programming-language.rst Mauro Carvalho Chehab
2020-03-03 17:19   ` Nick Desaulniers
2020-03-04  8:34   ` Federico Vaga
2020-03-10 17:55   ` Jonathan Corbet
2020-03-03 15:50 ` [PATCH 7/9] docs: filesystems: fuse.rst: supress a Sphinx warning Mauro Carvalho Chehab
2020-03-10 17:55   ` Jonathan Corbet
2020-03-03 15:50 ` [PATCH 8/9] docs: perf: imx-ddr.rst: get rid of a warning Mauro Carvalho Chehab
2020-03-10 17:56   ` Jonathan Corbet
2020-03-03 15:50 ` [PATCH 9/9] docs: hw-vuln: tsx_async_abort.rst: get rid of an unused ref Mauro Carvalho Chehab
2020-03-10 17:57   ` Jonathan Corbet
2020-03-03 20:42 ` [PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format Tom Zanussi
2020-03-03 20:48 ` Steven Rostedt
2020-03-10 17:49   ` Jonathan Corbet

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=637fc605eb2fe6e27d9983ee5c30d78989618313.1583250595.git.mchehab+huawei@kernel.org \
    --to=mchehab+huawei@kernel.org \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --subject='Re: [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings' \
    /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

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox