lkml.org 
[lkml]   [2018]   [Nov]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
Date
From
SubjectRe: [patch 2/2] Documentation/process: Add tip tree handbook
On Wed, 7 Nov 2018, Thomas Gleixner wrote:

> Add a document to the subsystem/maintainer handbook section, which explains
> what the tip tree is, how it operates and what rules and expectations it
> has.

Peter asked me to add a section about locking comments. I added it and
forgot to refresh the patch before sending. Delta patch below.

Thanks,

tglx
---
--- a/Documentation/process/maintainer-tip.rst
+++ b/Documentation/process/maintainer-tip.rst
@@ -578,6 +578,29 @@ Sentences in comments start with a upper
usage of descriptive function names often replaces these tiny comments.
Apply common sense as always.

+
+Documenting locking requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ Documenting locking requirements is a good thing, but comments are not
+ necessarily the best choice. Instead of writing::
+
+ /* Caller must hold foo->lock */
+ void func(struct foo *foo)
+ {
+ ...
+ }
+
+ Please use::
+
+ void func(struct foo *foo)
+ {
+ lockdep_assert_held(&foo->lock);
+ ...
+ }
+
+ The latter enables run time debugging when lockdep is enabled which
+ verifies that all callers hold the lock. Comments can't do that.
+

Bracket rules
^^^^^^^^^^^^^
\
 
 \ /
  Last update: 2018-11-07 18:44    [W:0.146 / U:2.208 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site