[RFC] [BZ 14417] Document condvar synchronization

[Jeff Law]

On 09/26/2012 10:41 AM, Torvald Riegel wrote:
> On Wed, 2012-09-26 at 10:34 -0600, Jeff Law wrote:
>> On 09/26/2012 10:05 AM, Torvald Riegel wrote:
>>> On Fri, 2012-09-21 at 12:21 -0600, Jeff Law wrote:
>>>> On 09/21/2012 12:03 PM, Jakub Jelinek wrote:
>>>>> On Fri, Sep 21, 2012 at 02:34:46PM +0200, Torvald Riegel wrote:
>>>>>>        Add explanation of condvar synchronization.
>>>>>
>>>>> I believe documentation for how condvars work should be in
>>>>> nptl/DESIGN-condvar.txt (which exists, but is slightly out of date).
>>>
>>> Putting it in DESIGN-condvar.txt is fine with me if everyone prefers
>>> that.  However, I think it's better to put it closer to the source; that
>>> way, it's less easy to forget updating it.
>> So how about putting the additional documentation in DESIGN-condvar.txt
>> with a reference back to it from the various C & assembly implementations?
>
> Fine with me, if people prefer that.
>
> What form should the citation take? Something like:
>
> See DESIGN-condvar.txt for documentation and as background to some of
> the comments in the code.  Update it whenever you change the code.
>
> Or without the update reminder?
I'd include the reminder ;-)  Maybe, just maybe, someone will read it 
and follow its request.

jeff