Re: [patch 2/2] Documentation/process: Add tip tree handbook

[Paul E. McKenney]

On Wed, Nov 07, 2018 at 06:44:07PM +0100, Thomas Gleixner wrote:
> 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.

     In PROVE_LOCKING kernels, lockdep_assert_held() emits a warning
     if the caller doesn't hold the lock.  Comments can't do that.

							Thanx, Paul