Address requests for more documentation from

http://codereview.chromium.org/2023003 and 
http://codereview.chromium.org/2020002

BUG=none
TEST=none

Review URL: http://codereview.chromium.org/2094001

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@47455 0039d316-1c4b-4281-b951-d872f2087c98

2 files changed, 22 insertions, 0 deletions

diff --git a/base/singleton.h b/base/singleton.h
index 718834b..507c7f4 100644
--- a/base/singleton.h
+++ b/base/singleton.h
@@ -46,6 +46,23 @@ struct LeakySingletonTraits : public DefaultSingletonTraits<Type> {
 // for the singleton instance from a static buffer.  The singleton will
 // be cleaned up at exit, but can't be revived after destruction unless
 // the Resurrect() method is called.
+//
+// This is useful for a certain category of things, notably logging and
+// tracing, where the singleton instance is of a type carefully constructed to
+// be safe to access post-destruction.
+// In logging and tracing you'll typically get stray calls at odd times, like
+// during static destruction, thread teardown and the like, and there's a
+// termination race on the heap-based singleton - e.g. if one thread calls
+// get(), but then another thread initiates AtExit processing, the first thread
+// may call into an object residing in unallocated memory. If the instance is
+// allocated from the data segment, then this is survivable.
+//
+// The destructor is to deallocate system resources, in this case to unregister
+// a callback the system will invoke when logging levels change. Note that
+// this is also used in e.g. Chrome Frame, where you have to allow for the
+// possibility of loading briefly into someone else's process space, and
+// so leaking is not an option, as that would sabotage the state of your host
+// process once you've unloaded.
 template <typename Type>
 struct StaticMemorySingletonTraits {
   // WARNING: User has to deal with get() in the singleton class
diff --git a/base/trace_event.h b/base/trace_event.h
index 7537b97..ff2119a 100644
--- a/base/trace_event.h
+++ b/base/trace_event.h
@@ -20,6 +20,11 @@
 #if defined(OS_WIN)
 // On Windows we always pull in an alternative implementation
 // which logs to Event Tracing for Windows.
+//
+// Note that the Windows implementation is always enabled, irrespective the
+// value of the CHROMIUM_ENABLE_TRACE_EVENT define. The Windows implementation
+// is controlled by Event Tracing for Windows, which will turn tracing on only
+// if there is someone listening for the events it generates.
 #include "base/trace_event_win.h"
 #else  // defined(OS_WIN)