[Boost-bugs] [Boost C++ Libraries] #9471: Synchronization documentation nits

Subject: [Boost-bugs] [Boost C++ Libraries] #9471: Synchronization documentation nits
From: Boost C++ Libraries (noreply_at_[hidden])
Date: 2013-12-04 17:25:10

#9471: Synchronization documentation nits
----------------------------------+----------------------
 Reporter:  Richard <legalize@…>  |      Owner:  anthonyw
     Type:  Bugs                  |     Status:  new
Milestone:  To Be Determined      |  Component:  thread
  Version:  Boost 1.55.0          |   Severity:  Problem
 Keywords:                        |
----------------------------------+----------------------
 The page
 http://www.boost.org/doc/libs/1_55_0/doc/html/thread/synchronization.html

 has a number of minor hiccups when reading it.  Here are some suggested
 corrections.

 Section: Concurrent threads of execution

 "On C++11 (Boost) concurrent execution of a component is obtained by means
 of the std::thread(boost::thread):"

 should read

 "In C++11 (Boost) concurrent execution of a component is obtained by means
 of the std::thread (boost::thread) class:"

 Section: Internal locking

 "The above example works well as long as the bankAgent and Joe doesn't
 access JoesAccount at the same time."

 should read

 "The above example works well as long as the components bankAgent and Joe
 don't access JoesAccount at the same time."

 "Mutex is a simple and basic mechanism for obtaining synchronization."

 should read

 "A mutex is a simple and basic mechanism..."

 "In the code below, guard's constructor locks the passed-in object this,
 and guard's destructor unlocks this."

 It doesn't lock 'this', which is 'guard', it locks 'mtx_'.  This should
 read

 "In the code below, guard's constructor locks the passed-in object mtx_,
 and guard's destructor unlocks mtx."

 "Notice that the code above doesn't compiles, the mtx_ field is private."

 should read

 "Notice that the code above doesn't compile, the mtx_ field is private."

 "make mtx_ public which seams odd"

 should read

 "make mtx_ public which seems odd"

 Section: External Locking -- strict_lock and externally_locked classes

 "This tutorial is an adaptation of the paper of Andrei Alexandrescu..."

 should read

 "This tutorial is an adaptation of the paper by Andrei Alexandrescu..."

 Section: Locks as Permits

 All the other section titles capitalize only the first word of the title,
 why is Permits capitalized here?

 Before the first code block, the text says:

 "While we're at it, let's disable operator new and operator delete."

 but the code block shown doesn't do this, it uses C++11 delete syntax to
 remove the default constructor, copy constructor and assignment operator,
 but not operator new and delete.

 "Now, if you want the benefit of internal locking, you simply call
 Deposit(int) and Withdraw(int)."

 The method signatures for Deposit and Withdraw in this sentence are not in
 a fixed-width font.

 Section: Allowing other strict locks

 "As unique_lock is not a strict lock the following code doesn't compiles:"

 should read

 "As unique_lock is not a strict lock the following code doesn't compile:"

 "We need a way to transfer the ownership from the unique_lock to a
 strict_lock the time we are working with savingsAcct_..."

 should read

 "We need a way to transfer the ownership from the unique_lock to a
 strict_lock during the time we are working with savingsAcct_..."

 "Store which kind of reference we have stored,and in the destructor..."

 should read

 "We also need to store which kind of reference we have stored, and in the
 destructor..."

 "This seams too complicated to me."

 should read

 "This seems too complicated to me."

 "...we need either to duplicate every function taking a strict_lock or
 make these function templates functions."

 should read

 "...we need either to duplicate every function taking a strict_lock or
 make these function templates."

 "We must add some static metafunction that check that the Locker parameter
 is a strict lock."

 should read

 "We must add some static metafunction that checks that the Locker
 parameter is a strict lock."

 "We need to belive it "sur parole"."

 should read

 "We need to believe it "sur parole"."

 ("sur parole"?  Use an appropriate English expression.  I googled this and
 couldn't find anything except a translation from French.)

 "Well let me show how this nested_strict_lock clss looks like and..."

 should read

 "Well let me show what this nested_strict_lock_class looks like and..."

 "On destruction he will restore the ownership."

 should read

 "On destruction it will restore the ownership."

 "Note also that the Locker needs to have already a reference to the mutex
 otherwise an exception is thrown and the use of the lock_traits."

 This is pretty awkward wording; it should read

 "Note the use of lock_traits and that the Locker needs to have a reference
 to the mutex otherwise and exception is thrown."

 OK, there are probably more, but that's all I have time for right now.

-- 
Ticket URL: <https://svn.boost.org/trac/boost/ticket/9471>
Boost C++ Libraries <http://www.boost.org/>
Boost provides free peer-reviewed portable C++ source libraries.