Update BStopWatch documentation

docs/user/support/StopWatch.dox

@@ -4,6 +4,7 @@
  *
  * Documentation written by:
  *		Niels Sascha Reedijk, niels.reedijk@gmail.com
+ *		John Scipione, jscipione@gmail.com
  *
  * Corresponds to:
  *		headers/os/support/StopWatch.h rev 19972
@@ -23,92 +24,105 @@
 	\class BStopWatch
 	\ingroup support
 	\ingroup libbe
-	\brief A timer class.
-
-	This class provides method to time events. The interface is designed to 
-	behave like a physical stopwatch. It is especially useful for debugging 
-	certain parts of your code, since it can behave like a 'cheap' profiler. 
+	\brief A simple class used to time events like a stop watch.
+
+	The interface of this class is designed to behave like a physical
+	stop watch. It is useful for debugging parts of your code acting as a
+	quick and dirty profiler.
+
+	To use this class first create a BStopWatch object, this starts the timer
+	going. You may call Suspend() and Resume() to start and stop the stop
+	watch. Call ElapsedTime() to get the current timer count at any time. You
+	may call Lap() to start a new lap (up to 10 laps are supported) or call
+	Reset() to reset the timer back to 0 clearing all lap info. When the
+	object is destroyed the timing information is streamed to standard out
+	unless you set the \a silent parameter to \c true in the constructor.
 */
 
 
 /*!
 	\fn BStopWatch::BStopWatch(const char *name, bool silent)
-	\brief Construct a BStopWatch object and starts the timer.
+	\brief Constructs a BStopWatch object and starts the timer.
 
-	The constructor creates a clean BStopWatch object. This object
-	can be given a name. As soon as the object is created, the time
-	will start ticking away. This class is designed to be usuable as a primitive
-	profiling tool.
+	This method creates a new BStopWatch object. As soon as the object is
+	created the timer starts ticking away.
 
-	If you are profiling your code with this class, pass true as the
-	\a silent parameter. Whenever the object is destroyed, information on
-	the elapsed time will be streamed to standard output.
+	If you are profiling your code with this class, pass \c true to the
+	\a silent parameter. Doing so causes elapsed time information to be
+	streamed to standard output when when the object is destroyed.
 
-	\param name The name you want to give this object. You may pass \c NULL.
-	\param silent Pass \c true if you want to use this object as a simple
-		   profiler.
+	\param name The name of the stop watch. You may pass \c NULL to create an
+	       anonymous stop watch.
+	\param silent Pass \c true to suppress time information from streaming to
+	       standard output when the object is destroyed.
 */
 
 
 /*!
 	\fn BStopWatch::~BStopWatch()
-	\brief Destructor.
+	\brief Destroys the object stopping the timer.
 
-	Destroys the object. If the object was constructed with the parameter 
-	silent set t to false, this destructor will print information on the elapsed
-	time to standard output.
+	If \a silent was set to \c false in the constructor then this method
+	will print elapsed time information to standard output.
 */
 
 
 /*!
 	\fn void BStopWatch::Resume()
-	\brief Resume the timer when it is in a suspended state.
+	\brief Resume the timer from a suspended state.
+
 	\see Suspend()
 */
 
 
 /*!
 	\fn void BStopWatch::Suspend()
 	\brief Suspend the timer.
+
 	\see Resume()
 */
 
 
 /*!
 	\fn bigtime_t BStopWatch::Lap()
-	\brief Start a new lap.
-
-	This method sets a lap. With the current implementation you are unable to
-	actually retrieve the timings of the laps. This is only printed to the
-	standard output when the object is destroyed. Thus making this tool only
-	usuable for use when doing some profiling.
-
-	\attention Please note that the current implementation is limited to 10 laps.
-	The value returned is the time that has passed since the timer was started
-	(and not the time that has passed since the last lap). Any lap call beyond
-	the 10th lap will overwrite the last value. Note that if the timer is
-	suspended, nothing happens and the method will return 0.
+	\brief Starts a new timer lap.
+
+	In the current implementation you are unable to actually retrieve the
+	timings of each lap, they are only printed to the standard output when the
+	object is destroyed. This makes the Lap() method only usable when doing
+	some types of profiling.
+
+	\note The current implementation is limited to 10 laps. The value returned
+	      is the time that has passed since the timer was last started (not
+	      the time that has passed since the last lap). Any call to Lap()
+	      beyond the 10th lap will overwrite the last value. Calling Lap()
+	      while the timer is suspended does nothing and returns 0.
 */
 
 
 /*!
 	\fn bigtime_t BStopWatch::ElapsedTime() const
-	\brief Get the elapsed time the object has counted.
+	\brief Gets the elapsed time the object has counted.
+
 	\return The elapsed time in microseconds.
 */
 
 
 /*!
 	\fn void BStopWatch::Reset()
-	\brief Restart the timer.
+	\brief Restarts the timer.
 
-	Resets the object: it clears the start time, it clears the stored laps and it
+	Resets the stop watch clearing the start time and stored laps and
 	restarts the timer.
 */
 
 
 /*!
-	\fn const char *BStopWatch::Name() const
-	\brief Get the name.
-	\return the name given to the object at creation time.
+	\fn const char* BStopWatch::Name() const
+	\brief Returns the name of the stop watch.
+
+	If name was set to \c NULL in the constructor this method returns a blank
+	string.
+
+	\return the name of the stop watch set in the constructor.
 */