Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1640466 > unrolled thread

[PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-12 16:10 +0200
    Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-12 18:50 +0200
      Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 00:00 +0200
        Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-13 00:20 +0200
          Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 11:50 +0200
          Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-15 09:10 +0200
            Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-15 11:10 +0200
              Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-15 11:40 +0200
                Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST Jani Nikula <jani.nikula@linux.intel.com> - 2017-05-15 12:30 +0200
                  Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-15 13:50 +0200
                    Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST Jani Nikula <jani.nikula@linux.intel.com> - 2017-05-15 14:10 +0200
                    Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-15 18:50 +0200
                      Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 12:20 +0200
                    Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-15 19:30 +0200
                      Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-16 13:20 +0200
                        Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 13:50 +0200
        Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-13 00:20 +0200
        Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-13 00:20 +0200

#1640466 — [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

There are a few issues on some kernel-doc markups that was
causing troubles with kernel-doc output on ReST format.
Fix them.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/linux/mutex.h  |  6 +++---
 kernel/futex.c         | 40 ++++++++++++++++++++--------------------
 kernel/locking/mutex.c |  6 ++++--
 3 files changed, 27 insertions(+), 25 deletions(-)

diff --git a/include/linux/mutex.h b/include/linux/mutex.h
index 1127fe31645d..ffcba1f337da 100644
--- a/include/linux/mutex.h
+++ b/include/linux/mutex.h
@@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum {
  * raisins, and once those are gone this will be removed.
  *
  * Returns:
- *  MUTEX_TRYLOCK_FAILED    - trylock failed,
- *  MUTEX_TRYLOCK_SUCCESS   - lock acquired,
- *  MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
+ *  - MUTEX_TRYLOCK_FAILED    - trylock failed,
+ *  - MUTEX_TRYLOCK_SUCCESS   - lock acquired,
+ *  - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
  */
 static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
 mutex_trylock_recursive(struct mutex *lock)
diff --git a/kernel/futex.c b/kernel/futex.c
index 357348a6cf6b..b8ae87d227da 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -488,7 +488,7 @@ static void drop_futex_key_refs(union futex_key *key)
  *
  * Return: a negative error code or 0
  *
- * The key words are stored in *key on success.
+ * The key words are stored in @key on success.
  *
  * For shared mappings, it's (page->index, file_inode(vma->vm_file),
  * offset_within_page).  For private mappings, it's (uaddr, current->mm).
@@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
  * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)
  *
  * Return:
- *  0 - ready to wait;
- *  1 - acquired the lock;
- * <0 - error
+ *  -  0 - ready to wait;
+ *  -  1 - acquired the lock;
+ *  - <0 - error
  *
  * The hb->lock and futex_key refs shall be held by the caller.
  */
@@ -1717,9 +1717,9 @@ void requeue_pi_wake_futex(struct futex_q *q, union futex_key *key,
  * hb1 and hb2 must be held by the caller.
  *
  * Return:
- *  0 - failed to acquire the lock atomically;
- * >0 - acquired the lock, return value is vpid of the top_waiter
- * <0 - error
+ *  -  0 - failed to acquire the lock atomically;
+ *  - >0 - acquired the lock, return value is vpid of the top_waiter
+ *  - <0 - error
  */
 static int futex_proxy_trylock_atomic(u32 __user *pifutex,
 				 struct futex_hash_bucket *hb1,
@@ -1785,8 +1785,8 @@ static int futex_proxy_trylock_atomic(u32 __user *pifutex,
  * uaddr2 atomically on behalf of the top waiter.
  *
  * Return:
- * >=0 - on success, the number of tasks requeued or woken;
- *  <0 - on error
+ *  - >=0 - on success, the number of tasks requeued or woken;
+ *  -  <0 - on error
  */
 static int futex_requeue(u32 __user *uaddr1, unsigned int flags,
 			 u32 __user *uaddr2, int nr_wake, int nr_requeue,
@@ -2142,8 +2142,8 @@ static inline void queue_me(struct futex_q *q, struct futex_hash_bucket *hb)
  * be paired with exactly one earlier call to queue_me().
  *
  * Return:
- *   1 - if the futex_q was still queued (and we removed unqueued it);
- *   0 - if the futex_q was already removed by the waking thread
+ *  - 1 - if the futex_q was still queued (and we removed unqueued it);
+ *  - 0 - if the futex_q was already removed by the waking thread
  */
 static int unqueue_me(struct futex_q *q)
 {
@@ -2333,9 +2333,9 @@ static long futex_wait_restart(struct restart_block *restart);
  * acquire the lock. Must be called with the hb lock held.
  *
  * Return:
- *  1 - success, lock taken;
- *  0 - success, lock not taken;
- * <0 - on error (-EFAULT)
+ *  -  1 - success, lock taken;
+ *  -  0 - success, lock not taken;
+ *  - <0 - on error (-EFAULT)
  */
 static int fixup_owner(u32 __user *uaddr, struct futex_q *q, int locked)
 {
@@ -2422,8 +2422,8 @@ static void futex_wait_queue_me(struct futex_hash_bucket *hb, struct futex_q *q,
  * with no q.key reference on failure.
  *
  * Return:
- *  0 - uaddr contains val and hb has been locked;
- * <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
+ *  -  0 - uaddr contains val and hb has been locked;
+ *  - <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
  */
 static int futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags,
 			   struct futex_q *q, struct futex_hash_bucket **hb)
@@ -2895,8 +2895,8 @@ static int futex_unlock_pi(u32 __user *uaddr, unsigned int flags)
  * called with the hb lock held.
  *
  * Return:
- *  0 = no early wakeup detected;
- * <0 = -ETIMEDOUT or -ERESTARTNOINTR
+ *  -  0 = no early wakeup detected;
+ *  - <0 = -ETIMEDOUT or -ERESTARTNOINTR
  */
 static inline
 int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
@@ -2968,8 +2968,8 @@ int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
  * If 4 or 7, we cleanup and return with -ETIMEDOUT.
  *
  * Return:
- *  0 - On success;
- * <0 - On error
+ *  -  0 - On success;
+ *  - <0 - On error
  */
 static int futex_wait_requeue_pi(u32 __user *uaddr, unsigned int flags,
 				 u32 val, ktime_t *abs_time, u32 bitset,
diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
index 198527a62149..b88b493c9512 100644
--- a/kernel/locking/mutex.c
+++ b/kernel/locking/mutex.c
@@ -227,9 +227,11 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
  * (or statically defined) before it can be locked. memset()-ing
  * the mutex to 0 is not allowed.
  *
- * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
+ * .. note::
+ *
+ *   The CONFIG_DEBUG_MUTEXES .config option turns on debugging
  *   checks that will enforce the restrictions and will also do
- *   deadlock debugging. )
+ *   deadlock debugging.
  *
  * This function is similar to (but not equivalent to) down().
  */
-- 
2.9.3

[toc] | [next] | [standalone]

#1640587 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Fri, May 12, 2017 at 10:59:47AM -0300, Mauro Carvalho Chehab wrote:
> There are a few issues on some kernel-doc markups that was
> causing troubles with kernel-doc output on ReST format.
> Fix them.
> 
> No functional changes.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

No objection. One question, rather than prefixing the bulleted list of return
codes with a "-" which has no ReST meaning I could find, should we use "*"
instead which would be converted to a bullet it formatted documentation?

> @@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
>   * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)
>   *
>   * Return:
> - *  0 - ready to wait;
> - *  1 - acquired the lock;
> - * <0 - error
> + *  -  0 - ready to wait;
> + *  -  1 - acquired the lock;
> + *  - <0 - error
>   *

e.g.

 * Return:
 *  *  0 - ready to wait
 *  *  1 - acquired the lock
 *  * <0 - error

I'm fine with either though, just curious if this would be an improvement, or if
we have an established policy (which I didn't find in the docs on docs...).

Acked-by: Darren Hart (VMware) <dvhart@infradead.org>

-- 
Darren Hart
VMware Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1640779 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

Em Fri, 12 May 2017 09:41:22 -0700
Darren Hart <dvhart@infradead.org> escreveu:

> On Fri, May 12, 2017 at 10:59:47AM -0300, Mauro Carvalho Chehab wrote:
> > There are a few issues on some kernel-doc markups that was
> > causing troubles with kernel-doc output on ReST format.
> > Fix them.
> > 
> > No functional changes.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>  
> 
> No objection. One question, rather than prefixing the bulleted list of return
> codes with a "-" which has no ReST meaning I could find, should we use "*"
> instead which would be converted to a bullet it formatted documentation?

At least on Sphinx[1]:
	"A text block which begins with a "*", "+", "-", "•", "‣", or "⁃",
	 followed by whitespace, is a bullet list item"

I never tried "+", but both "-" and "*" produce the same visual.

[1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists

> 
> > @@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
> >   * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)
> >   *
> >   * Return:
> > - *  0 - ready to wait;
> > - *  1 - acquired the lock;
> > - * <0 - error
> > + *  -  0 - ready to wait;
> > + *  -  1 - acquired the lock;
> > + *  - <0 - error
> >   *  
> 
> e.g.
> 
>  * Return:
>  *  *  0 - ready to wait
>  *  *  1 - acquired the lock
>  *  * <0 - error
> 
> I'm fine with either though, just curious if this would be an improvement, or if
> we have an established policy (which I didn't find in the docs on docs...).

I prefer myself to use "-". IMHO, a dash is visually less polluted
than an asterisk, when reading text files, but I guess this is a
matter of taste.

> Acked-by: Darren Hart (VMware) <dvhart@infradead.org>

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1640784 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Sat, May 13, 2017 at 12:11:09AM +0200, Peter Zijlstra wrote:
> On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote:
> > >  * Return:
> > >  *  *  0 - ready to wait
> > >  *  *  1 - acquired the lock
> > >  *  * <0 - error
> > > 
> > > I'm fine with either though, just curious if this would be an improvement, or if
> > > we have an established policy (which I didn't find in the docs on docs...).
> > 
> > I prefer myself to use "-". IMHO, a dash is visually less polluted
> > than an asterisk, when reading text files, but I guess this is a
> > matter of taste.
> 
> Not to mention it just reads very awkward in a comment. I don't much
> care about it in any other context.

Agreed, the - is better (and equally functional - so yay).

> 
> And I really _really_ hate to see that rest crap spread here. Can't we
> just delete all that nonsense and go back to 80 column 7bit ASCII ?
> 

Depending on the source this could be a genuine appeal or satire.... :-D

In this case, I don't think the ReST changes (with -) make the comment block any
less readable in the C files.

> It is an incentive not to use kerneldoc..
> 

I like the kerneldoc if for no other reason that it helps keeps formatting
consistent. I would object if I started seeing XML or some other horrible
formatting style showing up in the code, but this honestly seems like a fairly
minimal imposition... but that's me.

-- 
Darren Hart
VMware Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1640868 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

Em Fri, 12 May 2017 15:19:17 -0700
Darren Hart <dvhart@infradead.org> escreveu:

> On Sat, May 13, 2017 at 12:11:09AM +0200, Peter Zijlstra wrote:
> > On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote:  
> > > >  * Return:
> > > >  *  *  0 - ready to wait
> > > >  *  *  1 - acquired the lock
> > > >  *  * <0 - error
> > > > 
> > > > I'm fine with either though, just curious if this would be an improvement, or if
> > > > we have an established policy (which I didn't find in the docs on docs...).  
> > > 
> > > I prefer myself to use "-". IMHO, a dash is visually less polluted
> > > than an asterisk, when reading text files, but I guess this is a
> > > matter of taste.  
> > 
> > Not to mention it just reads very awkward in a comment. I don't much
> > care about it in any other context.  
> 
> Agreed, the - is better (and equally functional - so yay).
> 
> > 
> > And I really _really_ hate to see that rest crap spread here. Can't we
> > just delete all that nonsense and go back to 80 column 7bit ASCII ?
> >   
> 
> Depending on the source this could be a genuine appeal or satire.... :-D
> 
> In this case, I don't think the ReST changes (with -) make the comment block any
> less readable in the C files.
> 
> > It is an incentive not to use kerneldoc..

Very few kerneldoc markups need changes due to ReST introduction, and
usually is just whitespace/blank lines adjustment. Ok, someone could
try to improve the script to make it smarter[1], but, on my experiences
addressing it, usually doing the required changes make it visually
better on both C file and on PDF/LaTeX/HTML outputs.

[1] probably rewriting the entire script to work more like a lexical
    interpreter than a bunch of rejex expressions.

> I like the kerneldoc if for no other reason that it helps keeps formatting
> consistent. I would object if I started seeing XML or some other horrible
> formatting style showing up in the code, but this honestly seems like a fairly
> minimal imposition... but that's me.

IMHO, the best thing with kerneldoc is that it helps to keep the
documentation updated, as it warns when someone change the function
arguments without updating the comments.

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1641317 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Fri, May 12, 2017 at 03:19:17PM -0700, Darren Hart wrote:
> On Sat, May 13, 2017 at 12:11:09AM +0200, Peter Zijlstra wrote:

> > And I really _really_ hate to see that rest crap spread here. Can't we
> > just delete all that nonsense and go back to 80 column 7bit ASCII ?
> > 
> 
> Depending on the source this could be a genuine appeal or satire.... :-D

A bit of both of course ;-)

> In this case, I don't think the ReST changes (with -) make the comment block any
> less readable in the C files.
> 
> > It is an incentive not to use kerneldoc..
> > 
> 
> I like the kerneldoc if for no other reason that it helps keeps formatting
> consistent. I would object if I started seeing XML or some other horrible
> formatting style showing up in the code, but this honestly seems like a fairly
> minimal imposition... but that's me.

Well, I don't mind the '-' thing before return values too much, but the
below chunk is just pure drivel. It makes a perfectly good comment
worse.

--- a/kernel/locking/mutex.c
+++ b/kernel/locking/mutex.c
@@ -227,9 +227,11 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
  * (or statically defined) before it can be locked. memset()-ing
  * the mutex to 0 is not allowed.
  *
- * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
+ * .. note::
+ *
+ *   The CONFIG_DEBUG_MUTEXES .config option turns on debugging
  *   checks that will enforce the restrictions and will also do
- *   deadlock debugging. )
+ *   deadlock debugging.
  *
  * This function is similar to (but not equivalent to) down().
  */

[toc] | [prev] | [next] | [standalone]

#1641411 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

Em Mon, 15 May 2017 09:03:48 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:

> On Fri, May 12, 2017 at 03:19:17PM -0700, Darren Hart wrote:
> > On Sat, May 13, 2017 at 12:11:09AM +0200, Peter Zijlstra wrote:  
> 
> > > And I really _really_ hate to see that rest crap spread here. Can't we
> > > just delete all that nonsense and go back to 80 column 7bit ASCII ?
> > >   
> > 
> > Depending on the source this could be a genuine appeal or satire.... :-D  
> 
> A bit of both of course ;-)
> 
> > In this case, I don't think the ReST changes (with -) make the comment block any
> > less readable in the C files.
> >   
> > > It is an incentive not to use kerneldoc..
> > >   
> > 
> > I like the kerneldoc if for no other reason that it helps keeps formatting
> > consistent. I would object if I started seeing XML or some other horrible
> > formatting style showing up in the code, but this honestly seems like a fairly
> > minimal imposition... but that's me.  
> 
> Well, I don't mind the '-' thing before return values too much, but the
> below chunk is just pure drivel. It makes a perfectly good comment
> worse.
> 
> --- a/kernel/locking/mutex.c
> +++ b/kernel/locking/mutex.c
> @@ -227,9 +227,11 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
>   * (or statically defined) before it can be locked. memset()-ing
>   * the mutex to 0 is not allowed.
>   *
> - * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> + * .. note::
> + *
> + *   The CONFIG_DEBUG_MUTEXES .config option turns on debugging
>   *   checks that will enforce the restrictions and will also do
> - *   deadlock debugging. )
> + *   deadlock debugging.
>   *
>   * This function is similar to (but not equivalent to) down().
>   */

What caused problems with the orignal markup is that Sphinx is
highly oriented by indentation: different indentation levels on
it cause troubles. A minimal change for it to be parsed would as 
expected would be to remove the extra spaces that caused Sphinx
to misinterpret the paragraph, e. g.:

 * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
 * checks that will enforce the restrictions and will also do
 * deadlock debugging. )

But, if the intention of that spaces were to highlight the content
inside the parenthesis (with is what I assumed), then the
.. note markup will do the job. 

That's said, I guess it shouldn't be hard to add something at 
kernel-doc script to convert some specially-crafted tag (like "Note:")
to avoid having ReST notation for this specific case, e. g.:

 * Note:
 *
 * The CONFIG_DEBUG_MUTEXES .config option turns on debugging
 * checks that will enforce the restrictions and will also do
 * deadlock debugging.

Yet, IMHO, we should take some care to avoid adding much
translations to it, as, otherwise, we'll end by having two
markup languages instead of just one.

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1641490 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Mon, May 15, 2017 at 06:00:46AM -0300, Mauro Carvalho Chehab wrote:

> > Well, I don't mind the '-' thing before return values too much, but the
> > below chunk is just pure drivel. It makes a perfectly good comment
> > worse.
> > 
> > --- a/kernel/locking/mutex.c
> > +++ b/kernel/locking/mutex.c
> > @@ -227,9 +227,11 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
> >   * (or statically defined) before it can be locked. memset()-ing
> >   * the mutex to 0 is not allowed.
> >   *
> > - * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> > + * .. note::
> > + *
> > + *   The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> >   *   checks that will enforce the restrictions and will also do
> > - *   deadlock debugging. )
> > + *   deadlock debugging.
> >   *
> >   * This function is similar to (but not equivalent to) down().
> >   */
> 
> What caused problems with the orignal markup is that Sphinx is
> highly oriented by indentation: different indentation levels on
> it cause troubles. A minimal change for it to be parsed would as 
> expected would be to remove the extra spaces that caused Sphinx
> to misinterpret the paragraph, e. g.:
> 
>  * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
>  * checks that will enforce the restrictions and will also do
>  * deadlock debugging. )

That's ugly and doesn't read right either. Also C isn't whitespace
sensitive, so I don't feel we should add such brain damaged constraints
to our comments.

> But, if the intention of that spaces were to highlight the content
> inside the parenthesis (with is what I assumed), then the
> .. note markup will do the job. 

The intention is to aid readability. Making comments worse so that some
retarded script can generate better html or whatnot is just that,
retarded.

Code matters, generated documentation not so much. I'll take a comment
that reads well over one that generates pretty html any day.

> That's said, I guess it shouldn't be hard to add something at 
> kernel-doc script to convert some specially-crafted tag (like "Note:")
> to avoid having ReST notation for this specific case, e. g.:
> 
>  * Note:
>  *
>  * The CONFIG_DEBUG_MUTEXES .config option turns on debugging
>  * checks that will enforce the restrictions and will also do
>  * deadlock debugging.
> 
> Yet, IMHO, we should take some care to avoid adding much
> translations to it, as, otherwise, we'll end by having two
> markup languages instead of just one.

I'm all for _no_ markup language.

[toc] | [prev] | [next] | [standalone]

#1641521

On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> wrote:
> The intention is to aid readability. Making comments worse so that some
> retarded script can generate better html or whatnot is just that,
> retarded.
>
> Code matters, generated documentation not so much. I'll take a comment
> that reads well over one that generates pretty html any day.

The deal is that if you start your comments with "/**" they'll be
processed with the retarded script to produce pretty html.

For the most part the comments that generate pretty html also read well,
and we don't expect or want anyone to go overboard with markup. I don't
think it's unreasonable to make small concessions to improve generated
documentation for people who care about it even if you don't.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1641580 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:
> On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> wrote:
> > The intention is to aid readability. Making comments worse so that some
> > retarded script can generate better html or whatnot is just that,
> > retarded.
> >
> > Code matters, generated documentation not so much. I'll take a comment
> > that reads well over one that generates pretty html any day.
> 
> The deal is that if you start your comments with "/**" they'll be
> processed with the retarded script to produce pretty html.
> 
> For the most part the comments that generate pretty html also read well,
> and we don't expect or want anyone to go overboard with markup. I don't
> think it's unreasonable to make small concessions to improve generated
> documentation for people who care about it even if you don't.

No. Such a concession has pure negative value. It opens the door to more
patches converting this or that comment to be prettier or whatnot. And
before you know it there's a Markus like idiot spamming you with dozens
of crap patches to prettify the generated crud.

Not to mention that this would mean having to learn this rest crud in
order to write these comments.

All things I'm not prepared to do.


I'm all for useful comments, but I see no value _at_all_ in this
generated nonsense. The only reason I sometimes use the docbook comment
style is because its fairly uniform and the build bot gets you a warning
when your function signature no longer matches with the comment. But
if you make this painful I'll simply stop using them.

[toc] | [prev] | [next] | [standalone]

#1641600

On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> wrote:
> On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:
>> On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> wrote:
>> > The intention is to aid readability. Making comments worse so that some
>> > retarded script can generate better html or whatnot is just that,
>> > retarded.
>> >
>> > Code matters, generated documentation not so much. I'll take a comment
>> > that reads well over one that generates pretty html any day.
>> 
>> The deal is that if you start your comments with "/**" they'll be
>> processed with the retarded script to produce pretty html.
>> 
>> For the most part the comments that generate pretty html also read well,
>> and we don't expect or want anyone to go overboard with markup. I don't
>> think it's unreasonable to make small concessions to improve generated
>> documentation for people who care about it even if you don't.
>
> No. Such a concession has pure negative value. It opens the door to more
> patches converting this or that comment to be prettier or whatnot. And
> before you know it there's a Markus like idiot spamming you with dozens
> of crap patches to prettify the generated crud.
>
> Not to mention that this would mean having to learn this rest crud in
> order to write these comments.
>
> All things I'm not prepared to do.
>
> I'm all for useful comments, but I see no value _at_all_ in this
> generated nonsense. The only reason I sometimes use the docbook comment
> style is because its fairly uniform and the build bot gets you a warning
> when your function signature no longer matches with the comment. But
> if you make this painful I'll simply stop using them.

I see plenty of value in the generated documentation, but I see zero
return on investment in spending any time trying to convince you about
any of it.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1641877 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Mon, May 15, 2017 at 01:49:19PM +0200, Peter Zijlstra wrote:
> On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:
> > On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> wrote:
> > > The intention is to aid readability. Making comments worse so that some
> > > retarded script can generate better html or whatnot is just that,
> > > retarded.
> > >
> > > Code matters, generated documentation not so much. I'll take a comment
> > > that reads well over one that generates pretty html any day.
> > 
> > The deal is that if you start your comments with "/**" they'll be
> > processed with the retarded script to produce pretty html.
> > 
> > For the most part the comments that generate pretty html also read well,
> > and we don't expect or want anyone to go overboard with markup. I don't
> > think it's unreasonable to make small concessions to improve generated
> > documentation for people who care about it even if you don't.
> 
> No. Such a concession has pure negative value. It opens the door to more
> patches converting this or that comment to be prettier or whatnot. And
> before you know it there's a Markus like idiot spamming you with dozens
> of crap patches to prettify the generated crud.

Well that I can certainly understand.

> 
> Not to mention that this would mean having to learn this rest crud in
> order to write these comments.

I have complete confidence in you here Peter :-b

> 
> All things I'm not prepared to do.
> 
> 
> I'm all for useful comments, but I see no value _at_all_ in this
> generated nonsense. The only reason I sometimes use the docbook comment
> style is because its fairly uniform and the build bot gets you a warning
> when your function signature no longer matches with the comment. But
> if you make this painful I'll simply stop using them.
> 

Making documentation more accessible to people is a good thing. This type of
automated publication reduces the barrier to access. The lack of this kind of
tooling, honestly, also discourages participation among some groups of
of capable contributors.

That said, I support the direction both Mauro and Peter have voiced to minimize
the impact to comment blocks. What does rest do with this formatting it doesn't
understand - does it fail gracefully? Falling back to <verbatim> or something
like that?

-- 
Darren Hart
VMware Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1642390 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

Em Mon, 15 May 2017 09:40:44 -0700
Darren Hart <dvhart@infradead.org> escreveu:

> On Mon, May 15, 2017 at 01:49:19PM +0200, Peter Zijlstra wrote:
> > On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:  
> > > On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> wrote:  
> > > > The intention is to aid readability. Making comments worse so that some
> > > > retarded script can generate better html or whatnot is just that,
> > > > retarded.
> > > >
> > > > Code matters, generated documentation not so much. I'll take a comment
> > > > that reads well over one that generates pretty html any day.  
> > > 
> > > The deal is that if you start your comments with "/**" they'll be
> > > processed with the retarded script to produce pretty html.
> > > 
> > > For the most part the comments that generate pretty html also read well,
> > > and we don't expect or want anyone to go overboard with markup. I don't
> > > think it's unreasonable to make small concessions to improve generated
> > > documentation for people who care about it even if you don't.  
> > 
> > No. Such a concession has pure negative value. It opens the door to more
> > patches converting this or that comment to be prettier or whatnot. And
> > before you know it there's a Markus like idiot spamming you with dozens
> > of crap patches to prettify the generated crud.  
> 
> Well that I can certainly understand.
> 
> > 
> > Not to mention that this would mean having to learn this rest crud in
> > order to write these comments.  
> 
> I have complete confidence in you here Peter :-b
> 
> > 
> > All things I'm not prepared to do.
> > 
> > 
> > I'm all for useful comments, but I see no value _at_all_ in this
> > generated nonsense. The only reason I sometimes use the docbook comment
> > style is because its fairly uniform and the build bot gets you a warning
> > when your function signature no longer matches with the comment. But
> > if you make this painful I'll simply stop using them.
> >   
> 
> Making documentation more accessible to people is a good thing. This type of
> automated publication reduces the barrier to access. The lack of this kind of
> tooling, honestly, also discourages participation among some groups of
> of capable contributors.
> 
> That said, I support the direction both Mauro and Peter have voiced to minimize
> the impact to comment blocks. What does rest do with this formatting it doesn't
> understand - does it fail gracefully? Falling back to <verbatim> or something
> like that?

ReST produces a warning or error if it finds something it can't
parse, but it usually doesn't crash. The result of its output usually
is not what you would expect on such cases, though.

So, IMHO, the bare minimum to do is to make sure that it won't produce
errors/warnings.

PS.: kernel-doc itself also produce errors/warnings, if the vars at
the kernel-doc block don't match the ones at the function or if a
documented function was added or removed.

-

That's said, on the subsystems I maintain, I'm not satisfied with the
bare minimum ;) I usually build the html output and look into it
to be sure that the output from kernel-doc also looks nice.

In the case of the media subsystem, we have a big book describing the 
userspace API. Non-eventual media developers read the uAPI docs in html
or pdf for API docs before coding. 

So, on media subsysem, we ended by adding a few ReST specific
markups[1] where added, in order to improve its readability
in html/pdf, but the main documentation just use what's specified at
Documentation/doc-guide/kernel-doc.rst.

[1] There aren't much such markups used there. As far as I remember,
    we use:

    - bulleted lists like:
	    return:
	      - value 1
	      - value 2
	      ...

    - **bold** when we need to bold something;

    - ``literal`` for complex literal strings that %FOO won't handle
      (e. g. when it contains space and/or special chars);

    - ".. note::" or ".. attention::" in order to bold important
      notes, when some function have special requirements 
      to be called (for example, the need to lock or unlock 
      some mutex or spin lock before calling it).

      For example, the description for "v4l2_ctrl_handler_init_class"
      at:
	http://www.infradead.org/~mchehab/kernel_docs/media/kapi/v4l2-controls.html

      uses an attention markup that bolds that such function should
      not be called directly by API clients.

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1641916 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

Em Mon, 15 May 2017 13:49:19 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:

> On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:
> > On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> wrote:  
> > > The intention is to aid readability. Making comments worse so that some
> > > retarded script can generate better html or whatnot is just that,
> > > retarded.
> > >
> > > Code matters, generated documentation not so much. I'll take a comment
> > > that reads well over one that generates pretty html any day.  
> > 
> > The deal is that if you start your comments with "/**" they'll be
> > processed with the retarded script to produce pretty html.
> > 
> > For the most part the comments that generate pretty html also read well,
> > and we don't expect or want anyone to go overboard with markup. I don't
> > think it's unreasonable to make small concessions to improve generated
> > documentation for people who care about it even if you don't.  
> 
> No. Such a concession has pure negative value. It opens the door to more
> patches converting this or that comment to be prettier or whatnot. And
> before you know it there's a Markus like idiot spamming you with dozens
> of crap patches to prettify the generated crud.

I see your point. Nobody wants a pile of senseless random prettify patches
on their queue. Yet, on the other hand, nobody wants lots of warnings/errors
produced when building the Kernel or the documentation, as it can ride
important things that would require fixes. So, subsystem maintainers
need to find what works best for the subsystems they care of. That's
not different than accepting/rejecting a random patch.

That's said, from my side, I don't like the way ReST handle indentation.
I would have preferred some markup dialect that would be less sensitive
to it. My personal preference were to use docutils or doxygen (but I'm 
pretty sure they would have other limitations). 

Yet, ReST is not a bad choice, as it allows extending its syntax by 
writing Python scripts and adding  to our tree, with has been an 
interesting feature to extend it to our needs.

Yet, every parser/dialect have limitations. We have to deal with it
somehow.

Currently, kernel-doc avoids some indentation issues. For example,
in the code code below:

	/**
	 *<tab>@v:<tab>foo
	 *<tab><tab>bar
	 ...
	 */

The position of '@v' output, in ReST, would mangle indentation,
depending on the way it is converted. Yet, kernel-doc handles it
well. So, at least on some cases, kernel-doc works fine with 
indentation differences, making it transparent to the user. 
The above produces the following ReST output:

		**Parameters**
	
		``v``
		  foo
		  bar

Both "Parameters" and "v" will be bold; "v" will use a monospaced
font[1].

So, at least for most parameter/description indentation, kernel-doc
does the right thing.

[1 ] Btw, the *only* way I found on ReST notation to produce a bold
     monotonic font is to use:

	``foo``
	  bar

    As doing **``foo``** or ``**foo**`` won't work - at least with
    Sphinx up to version 1.4.

At least on media, some vars are enums, and we want to describe
the possible values used at enums, like on this kernel-doc comment
snippet:

 * Entities have flags that describe the entity capabilities and state:
 *
 * %MEDIA_ENT_FL_DEFAULT
 *    indicates the default entity for a given type.
 *    This can be used to report the default audio and video devices or the
 *    default camera sensor.
 *

For it to work, kernel-doc should not mangle with whitespaces, passing the
indentation to Sphinx.

So, I fail to see a way to avoid fixing the few cases where the
indentation doesn't follow what's expected by ReST.

Yet, if you prefer a minimalist change, I can remove the ReST-specific
dialect, as in the enclosed patch.

> Not to mention that this would mean having to learn this rest crud in
> order to write these comments.
> 
> All things I'm not prepared to do.
> 
> 
> I'm all for useful comments, but I see no value _at_all_ in this
> generated nonsense. The only reason I sometimes use the docbook comment
> style is because its fairly uniform and the build bot gets you a warning
> when your function signature no longer matches with the comment. But
> if you make this painful I'll simply stop using them.

Thanks,
Mauro

[PATCH v2] mutex, futex: adjust kernel-doc markups to generate ReST

There are a few issues on some kernel-doc markups that was
causing troubles with kernel-doc output on ReST format.
Fix them.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com

diff --git a/include/linux/mutex.h b/include/linux/mutex.h
index 1127fe31645d..ffcba1f337da 100644
--- a/include/linux/mutex.h
+++ b/include/linux/mutex.h
@@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum {
  * raisins, and once those are gone this will be removed.
  *
  * Returns:
- *  MUTEX_TRYLOCK_FAILED    - trylock failed,
- *  MUTEX_TRYLOCK_SUCCESS   - lock acquired,
- *  MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
+ *  - MUTEX_TRYLOCK_FAILED    - trylock failed,
+ *  - MUTEX_TRYLOCK_SUCCESS   - lock acquired,
+ *  - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
  */
 static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
 mutex_trylock_recursive(struct mutex *lock)
diff --git a/kernel/futex.c b/kernel/futex.c
index 357348a6cf6b..b8ae87d227da 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -488,7 +488,7 @@ static void drop_futex_key_refs(union futex_key *key)
  *
  * Return: a negative error code or 0
  *
- * The key words are stored in *key on success.
+ * The key words are stored in @key on success.
  *
  * For shared mappings, it's (page->index, file_inode(vma->vm_file),
  * offset_within_page).  For private mappings, it's (uaddr, current->mm).
@@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
  * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)
  *
  * Return:
- *  0 - ready to wait;
- *  1 - acquired the lock;
- * <0 - error
+ *  -  0 - ready to wait;
+ *  -  1 - acquired the lock;
+ *  - <0 - error
  *
  * The hb->lock and futex_key refs shall be held by the caller.
  */
@@ -1717,9 +1717,9 @@ void requeue_pi_wake_futex(struct futex_q *q, union futex_key *key,
  * hb1 and hb2 must be held by the caller.
  *
  * Return:
- *  0 - failed to acquire the lock atomically;
- * >0 - acquired the lock, return value is vpid of the top_waiter
- * <0 - error
+ *  -  0 - failed to acquire the lock atomically;
+ *  - >0 - acquired the lock, return value is vpid of the top_waiter
+ *  - <0 - error
  */
 static int futex_proxy_trylock_atomic(u32 __user *pifutex,
 				 struct futex_hash_bucket *hb1,
@@ -1785,8 +1785,8 @@ static int futex_proxy_trylock_atomic(u32 __user *pifutex,
  * uaddr2 atomically on behalf of the top waiter.
  *
  * Return:
- * >=0 - on success, the number of tasks requeued or woken;
- *  <0 - on error
+ *  - >=0 - on success, the number of tasks requeued or woken;
+ *  -  <0 - on error
  */
 static int futex_requeue(u32 __user *uaddr1, unsigned int flags,
 			 u32 __user *uaddr2, int nr_wake, int nr_requeue,
@@ -2142,8 +2142,8 @@ static inline void queue_me(struct futex_q *q, struct futex_hash_bucket *hb)
  * be paired with exactly one earlier call to queue_me().
  *
  * Return:
- *   1 - if the futex_q was still queued (and we removed unqueued it);
- *   0 - if the futex_q was already removed by the waking thread
+ *  - 1 - if the futex_q was still queued (and we removed unqueued it);
+ *  - 0 - if the futex_q was already removed by the waking thread
  */
 static int unqueue_me(struct futex_q *q)
 {
@@ -2333,9 +2333,9 @@ static long futex_wait_restart(struct restart_block *restart);
  * acquire the lock. Must be called with the hb lock held.
  *
  * Return:
- *  1 - success, lock taken;
- *  0 - success, lock not taken;
- * <0 - on error (-EFAULT)
+ *  -  1 - success, lock taken;
+ *  -  0 - success, lock not taken;
+ *  - <0 - on error (-EFAULT)
  */
 static int fixup_owner(u32 __user *uaddr, struct futex_q *q, int locked)
 {
@@ -2422,8 +2422,8 @@ static void futex_wait_queue_me(struct futex_hash_bucket *hb, struct futex_q *q,
  * with no q.key reference on failure.
  *
  * Return:
- *  0 - uaddr contains val and hb has been locked;
- * <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
+ *  -  0 - uaddr contains val and hb has been locked;
+ *  - <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
  */
 static int futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags,
 			   struct futex_q *q, struct futex_hash_bucket **hb)
@@ -2895,8 +2895,8 @@ static int futex_unlock_pi(u32 __user *uaddr, unsigned int flags)
  * called with the hb lock held.
  *
  * Return:
- *  0 = no early wakeup detected;
- * <0 = -ETIMEDOUT or -ERESTARTNOINTR
+ *  -  0 = no early wakeup detected;
+ *  - <0 = -ETIMEDOUT or -ERESTARTNOINTR
  */
 static inline
 int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
@@ -2968,8 +2968,8 @@ int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
  * If 4 or 7, we cleanup and return with -ETIMEDOUT.
  *
  * Return:
- *  0 - On success;
- * <0 - On error
+ *  -  0 - On success;
+ *  - <0 - On error
  */
 static int futex_wait_requeue_pi(u32 __user *uaddr, unsigned int flags,
 				 u32 val, ktime_t *abs_time, u32 bitset,
diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
index 198527a62149..858a07590e39 100644
--- a/kernel/locking/mutex.c
+++ b/kernel/locking/mutex.c
@@ -227,9 +227,9 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
  * (or statically defined) before it can be locked. memset()-ing
  * the mutex to 0 is not allowed.
  *
- * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
- *   checks that will enforce the restrictions and will also do
- *   deadlock debugging. )
+ * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging
+ * checks that will enforce the restrictions and will also do
+ * deadlock debugging)
  *
  * This function is similar to (but not equivalent to) down().
  */

[toc] | [prev] | [next] | [standalone]

#1642416 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Mon, May 15, 2017 at 02:22:39PM -0300, Mauro Carvalho Chehab wrote:
>  Yet, on the other hand, nobody wants lots of warnings/errors
> produced when building the Kernel or the documentation, as it can ride
> important things that would require fixes.

So would that actually generate a warn/error? Or just generate weird
output?

Because I'm perfectly fine with weird output.

Our primary interface to the code is a text editor, and things should be
readable in that form. Anything that detracts from that is a fail.

If people like to use web browsers (I don't) then I won't stop them, but
they have to realize they're the odd ducks out for viewing things
outside its native form.

> diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
> index 198527a62149..858a07590e39 100644
> --- a/kernel/locking/mutex.c
> +++ b/kernel/locking/mutex.c
> @@ -227,9 +227,9 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
>   * (or statically defined) before it can be locked. memset()-ing
>   * the mutex to 0 is not allowed.
>   *
> - * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> - *   checks that will enforce the restrictions and will also do
> - *   deadlock debugging. )
> + * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> + * checks that will enforce the restrictions and will also do
> + * deadlock debugging)
>   *
>   * This function is similar to (but not equivalent to) down().
>   */
> 
> 
> 

[toc] | [prev] | [next] | [standalone]

#1642450 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

Em Tue, 16 May 2017 13:16:56 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:

> On Mon, May 15, 2017 at 02:22:39PM -0300, Mauro Carvalho Chehab wrote:
> >  Yet, on the other hand, nobody wants lots of warnings/errors
> > produced when building the Kernel or the documentation, as it can ride
> > important things that would require fixes.  
> 
> So would that actually generate a warn/error? Or just generate weird
> output?

Both warn/error and weird output. From my side, the only reason
for writing this patch is to fix the warnings that would otherwise
be produced without it:

./kernel/futex.c:492: WARNING: Inline emphasis start-string without end-string.
./kernel/futex.c:1264: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:1721: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2338: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2426: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2899: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2972: WARNING: Block quote ends without a blank line; unexpected unindent.


> 
> Because I'm perfectly fine with weird output.
> 
> Our primary interface to the code is a text editor, and things should be
> readable in that form. Anything that detracts from that is a fail.
> 
> If people like to use web browsers (I don't) then I won't stop them, but
> they have to realize they're the odd ducks out for viewing things
> outside its native form.
> 
> > diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
> > index 198527a62149..858a07590e39 100644
> > --- a/kernel/locking/mutex.c
> > +++ b/kernel/locking/mutex.c
> > @@ -227,9 +227,9 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
> >   * (or statically defined) before it can be locked. memset()-ing
> >   * the mutex to 0 is not allowed.
> >   *
> > - * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> > - *   checks that will enforce the restrictions and will also do
> > - *   deadlock debugging. )
> > + * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> > + * checks that will enforce the restrictions and will also do
> > + * deadlock debugging)
> >   *
> >   * This function is similar to (but not equivalent to) down().
> >   */
> > 
> > 
> >   



Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1640786 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote:
> Em Fri, 12 May 2017 09:41:22 -0700
> Darren Hart <dvhart@infradead.org> escreveu:
> 
> > On Fri, May 12, 2017 at 10:59:47AM -0300, Mauro Carvalho Chehab wrote:
> > > There are a few issues on some kernel-doc markups that was
> > > causing troubles with kernel-doc output on ReST format.
> > > Fix them.
> > > 
> > > No functional changes.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>  
> > 
> > No objection. One question, rather than prefixing the bulleted list of return
> > codes with a "-" which has no ReST meaning I could find, should we use "*"
> > instead which would be converted to a bullet it formatted documentation?
> 
> At least on Sphinx[1]:
> 	"A text block which begins with a "*", "+", "-", "•", "‣", or "⁃",
> 	 followed by whitespace, is a bullet list item"
> 
> I never tried "+", but both "-" and "*" produce the same visual.
> 
> [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists
> 

Thanks, my search turned up a much shorter list of "list" special characters.

> > 
> > > @@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
> > >   * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)
> > >   *
> > >   * Return:
> > > - *  0 - ready to wait;
> > > - *  1 - acquired the lock;
> > > - * <0 - error
> > > + *  -  0 - ready to wait;
> > > + *  -  1 - acquired the lock;
> > > + *  - <0 - error
> > >   *  
> > 
> > e.g.
> > 
> >  * Return:
> >  *  *  0 - ready to wait
> >  *  *  1 - acquired the lock
> >  *  * <0 - error
> > 
> > I'm fine with either though, just curious if this would be an improvement, or if
> > we have an established policy (which I didn't find in the docs on docs...).
> 
> I prefer myself to use "-". IMHO, a dash is visually less polluted
> than an asterisk, when reading text files, but I guess this is a
> matter of taste.

Definitely agreed. - is preferable if it renders the same.

Thanks,

-- 
Darren Hart
VMware Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1640787 — Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote:
> >  * Return:
> >  *  *  0 - ready to wait
> >  *  *  1 - acquired the lock
> >  *  * <0 - error
> > 
> > I'm fine with either though, just curious if this would be an improvement, or if
> > we have an established policy (which I didn't find in the docs on docs...).
> 
> I prefer myself to use "-". IMHO, a dash is visually less polluted
> than an asterisk, when reading text files, but I guess this is a
> matter of taste.

Not to mention it just reads very awkward in a comment. I don't much
care about it in any other context.

And I really _really_ hate to see that rest crap spread here. Can't we
just delete all that nonsense and go back to 80 column 7bit ASCII ?

It is an incentive not to use kerneldoc..

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web