Bug 1046841 - Fix comment style of nsCOMPtr.h. r=froydnj
authorBirunthan Mohanathas <birunthan@mohanathas.com>
Mon, 25 Aug 2014 12:17:20 -0700
changeset 223094 db05fccb028c0c46217203d2d8e9fa8020b727d5
parent 223093 b373c1d4e8ae1c06a2cf3b4c1d6a4a9569b79936
child 223095 fe4f8a3cdb1991c1e6fba042dcab1fd345ad4357
push id3979
push userraliiev@mozilla.com
push dateMon, 13 Oct 2014 16:35:44 +0000
treeherdermozilla-beta@30f2cc610691 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersfroydnj
bugs1046841
milestone34.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1046841 - Fix comment style of nsCOMPtr.h. r=froydnj
xpcom/glue/nsCOMPtr.h
--- a/xpcom/glue/nsCOMPtr.h
+++ b/xpcom/glue/nsCOMPtr.h
@@ -3,56 +3,56 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 #ifndef nsCOMPtr_h___
 #define nsCOMPtr_h___
 
 /*
-  Having problems?
-
-  See the User Manual at:
-    http://www.mozilla.org/projects/xpcom/nsCOMPtr.html
-
-
-  nsCOMPtr
-    better than a raw pointer
-  for owning objects
-                       -- scc
-*/
+ * Having problems?
+ *
+ * See the User Manual at:
+ *   http://www.mozilla.org/projects/xpcom/nsCOMPtr.html
+ *
+ *
+ * nsCOMPtr
+ *   better than a raw pointer
+ * for owning objects
+ *                      -- scc
+ */
 
 #include "mozilla/Assertions.h"
 #include "mozilla/Attributes.h"
 #include "mozilla/Move.h"
 #include "mozilla/NullPtr.h"
 #include "mozilla/TypeTraits.h"
 
 #include "nsDebug.h" // for |NS_ABORT_IF_FALSE|, |NS_ASSERTION|
 #include "nsISupportsUtils.h" // for |nsresult|, |NS_ADDREF|, |NS_GET_TEMPLATE_IID| et al
 #include "nscore.h" // for |NS_COM_GLUE|
 
 #include "nsCycleCollectionNoteChild.h"
 
 
 /*
-  WARNING:
-    This file defines several macros for internal use only.  These macros begin with the
-    prefix |NSCAP_|.  Do not use these macros in your own code.  They are for internal use
-    only for cross-platform compatibility, and are subject to change without notice.
-*/
+ * WARNING: This file defines several macros for internal use only. These
+ * macros begin with the prefix |NSCAP_|. Do not use these macros in your own
+ * code. They are for internal use only for cross-platform compatibility, and
+ * are subject to change without notice.
+ */
 
 
 #ifdef _MSC_VER
+  // Under VC++, we win by inlining StartAssignment.
   #define NSCAP_FEATURE_INLINE_STARTASSIGNMENT
-    // under VC++, we win by inlining StartAssignment
 
-    // Also under VC++, at the highest warning level, we are overwhelmed  with warnings
-    //  about (unused) inline functions being removed.  This is to be expected with
-    //  templates, so we disable the warning.
+  // Also under VC++, at the highest warning level, we are overwhelmed with
+  // warnings about (unused) inline functions being removed. This is to be
+  // expected with templates, so we disable the warning.
   #pragma warning( disable: 4514 )
 #endif
 
 #define NSCAP_FEATURE_USE_BASE
 
 #ifdef DEBUG
   #define NSCAP_FEATURE_TEST_DONTQUERY_CASES
   #undef NSCAP_FEATURE_USE_BASE
@@ -70,72 +70,74 @@
 #else
   #define NS_MAY_ALIAS_PTR(t)    t*
 #endif
 
 #if defined(NSCAP_DISABLE_DEBUG_PTR_TYPES)
   #define NSCAP_FEATURE_USE_BASE
 #endif
 
-  /*
-    The following three macros (|NSCAP_ADDREF|, |NSCAP_RELEASE|, and |NSCAP_LOG_ASSIGNMENT|)
-      allow external clients the ability to add logging or other interesting debug facilities.
-      In fact, if you want |nsCOMPtr| to participate in the standard logging facility, you
-      provide (e.g., in "nsISupportsImpl.h") suitable definitions
-
-        #define NSCAP_ADDREF(this, ptr)         NS_ADDREF(ptr)
-        #define NSCAP_RELEASE(this, ptr)        NS_RELEASE(ptr)
-  */
+/*
+ * The following three macros (NSCAP_ADDREF, NSCAP_RELEASE, and
+ * NSCAP_LOG_ASSIGNMENT) allow external clients the ability to add logging or
+ * other interesting debug facilities. In fact, if you want |nsCOMPtr| to
+ * participate in the standard logging facility, you provide
+ * (e.g., in "nsISupportsImpl.h") suitable definitions
+ *
+ *   #define NSCAP_ADDREF(this, ptr)         NS_ADDREF(ptr)
+ *   #define NSCAP_RELEASE(this, ptr)        NS_RELEASE(ptr)
+ */
 
 #ifndef NSCAP_ADDREF
   #define NSCAP_ADDREF(this, ptr)     (ptr)->AddRef()
 #endif
 
 #ifndef NSCAP_RELEASE
   #define NSCAP_RELEASE(this, ptr)    (ptr)->Release()
 #endif
 
-  // Clients can define |NSCAP_LOG_ASSIGNMENT| to perform logging.
+// Clients can define |NSCAP_LOG_ASSIGNMENT| to perform logging.
 #ifdef NSCAP_LOG_ASSIGNMENT
-    // Remember that |NSCAP_LOG_ASSIGNMENT| was defined by some client so that we know
-    //  to instantiate |~nsGetterAddRefs| in turn to note the external assignment into
-    //  the |nsCOMPtr|.
+  // Remember that |NSCAP_LOG_ASSIGNMENT| was defined by some client so that we
+  // know to instantiate |~nsGetterAddRefs| in turn to note the external
+  // assignment into the |nsCOMPtr|.
   #define NSCAP_LOG_EXTERNAL_ASSIGNMENT
 #else
     // ...otherwise, just strip it out of the code
   #define NSCAP_LOG_ASSIGNMENT(this, ptr)
 #endif
 
 #ifndef NSCAP_LOG_RELEASE
   #define NSCAP_LOG_RELEASE(this, ptr)
 #endif
 
 namespace mozilla {
 
 struct unused_t;
 
 } // namespace mozilla
 
+/**
+ * already_AddRefed cooperates with nsCOMPtr to allow you to assign in a
+ * pointer _without_ |AddRef|ing it. You might want to use this as a return
+ * type from a function that produces an already |AddRef|ed pointer as a
+ * result.
+ *
+ * See also |getter_AddRefs()|, |dont_AddRef()|, and |class nsGetterAddRefs|.
+ *
+ * This type should be a nested class inside nsCOMPtr<T>.
+ *
+ * Yes, already_AddRefed could have been implemented as an nsCOMPtr_helper to
+ * avoid adding specialized machinery to nsCOMPtr ... but this is the simplest
+ * case, and perhaps worth the savings in time and space that its specific
+ * implementation affords over the more general solution offered by
+ * nsCOMPtr_helper.
+ */
 template<class T>
 struct already_AddRefed
-/*
-  ...cooperates with |nsCOMPtr| to allow you to assign in a pointer _without_
-  |AddRef|ing it.  You might want to use this as a return type from a function
-  that produces an already |AddRef|ed pointer as a result.
-
-  See also |getter_AddRefs()|, |dont_AddRef()|, and |class nsGetterAddRefs|.
-
-  This type should be a nested class inside |nsCOMPtr<T>|.
-
-  Yes, |already_AddRefed| could have been implemented as an |nsCOMPtr_helper| to
-  avoid adding specialized machinery to |nsCOMPtr| ... but this is the simplest
-  case, and perhaps worth the savings in time and space that its specific
-  implementation affords over the more general solution offered by
-  |nsCOMPtr_helper|.
-*/
 {
   /*
    * We want to allow returning nullptr from functions returning
    * already_AddRefed<T>, for simplicity.  But we also don't want to allow
    * returning raw T*, instead preferring creation of already_AddRefed<T> from
    * an nsRefPtr, nsCOMPtr, or the like.
    *
    * We address the latter requirement by making the (T*) constructor explicit.
@@ -162,17 +164,17 @@ struct already_AddRefed
 
   // The return and argument types here are arbitrarily selected so no
   // corresponding member function exists.
   typedef void (already_AddRefed::* MatchNullptr)(double, float);
   MOZ_IMPLICIT already_AddRefed(MatchNullptr aRawPtr) : mRawPtr(nullptr) {}
 
   explicit already_AddRefed(T* aRawPtr) : mRawPtr(aRawPtr) {}
 
-  // Disallowed.  Use move semantics instead.
+  // Disallowed. Use move semantics instead.
   already_AddRefed(const already_AddRefed<T>& aOther) MOZ_DELETE;
 
   already_AddRefed(already_AddRefed<T>&& aOther) : mRawPtr(aOther.take()) {}
 
   ~already_AddRefed() { MOZ_ASSERT(!mRawPtr); }
 
   // Specialize the unused operator<< for already_AddRefed, to allow
   // nsCOMPtr<nsIFoo> foo;
@@ -254,45 +256,44 @@ dont_AddRef(T* aRawPtr)
 template<class T>
 inline already_AddRefed<T>&&
 dont_AddRef(already_AddRefed<T>&& aAlreadyAddRefedPtr)
 {
   return mozilla::Move(aAlreadyAddRefedPtr);
 }
 
 
-
+/*
+ * An nsCOMPtr_helper transforms commonly called getters into typesafe forms
+ * that are more convenient to call, and more efficient to use with |nsCOMPtr|s.
+ * Good candidates for helpers are |QueryInterface()|, |CreateInstance()|, etc.
+ *
+ * Here are the rules for a helper:
+ *   - it implements |operator()| to produce an interface pointer
+ *   - (except for its name) |operator()| is a valid [XP]COM `getter'
+ *   - the interface pointer that it returns is already |AddRef()|ed (as from
+ *     any good getter)
+ *   - it matches the type requested with the supplied |nsIID| argument
+ *   - its constructor provides an optional |nsresult*| that |operator()| can
+ *     fill in with an error when it is executed
+ *
+ * See |class nsGetInterface| for an example.
+ */
 class nsCOMPtr_helper
-/*
-  An |nsCOMPtr_helper| transforms commonly called getters into typesafe forms
-  that are more convenient to call, and more efficient to use with |nsCOMPtr|s.
-  Good candidates for helpers are |QueryInterface()|, |CreateInstance()|, etc.
-
-  Here are the rules for a helper:
-    - it implements |operator()| to produce an interface pointer
-    - (except for its name) |operator()| is a valid [XP]COM `getter'
-    - the interface pointer that it returns is already |AddRef()|ed (as from any good getter)
-    - it matches the type requested with the supplied |nsIID| argument
-    - its constructor provides an optional |nsresult*| that |operator()| can fill
-      in with an error when it is executed
-
-  See |class nsGetInterface| for an example.
-*/
 {
 public:
   virtual nsresult NS_FASTCALL operator()(const nsIID&, void**) const = 0;
 };
 
 /*
-  |nsQueryInterface| could have been implemented as an |nsCOMPtr_helper| to
-  avoid adding specialized machinery in |nsCOMPtr|, But |do_QueryInterface|
-  is called often enough that the codesize savings are big enough to
-  warrant the specialcasing.
-*/
-
+ * nsQueryInterface could have been implemented as an nsCOMPtr_helper to avoid
+ * adding specialized machinery in nsCOMPtr, but do_QueryInterface is called
+ * often enough that the codesize savings are big enough to warrant the
+ * specialcasing.
+ */
 class NS_COM_GLUE MOZ_STACK_CLASS nsQueryInterface MOZ_FINAL
 {
 public:
   explicit
   nsQueryInterface(nsISupports* aRawPtr) : mRawPtr(aRawPtr) {}
 
   nsresult NS_FASTCALL operator()(const nsIID& aIID, void**) const;
 
@@ -328,27 +329,27 @@ do_QueryInterface(nsISupports* aRawPtr, 
   return nsQueryInterfaceWithError(aRawPtr, aError);
 }
 
 template<class T>
 inline void
 do_QueryInterface(already_AddRefed<T>&)
 {
   // This signature exists solely to _stop_ you from doing the bad thing.
-  //  Saying |do_QueryInterface()| on a pointer that is not otherwise owned by
-  //  someone else is an automatic leak.  See <http://bugzilla.mozilla.org/show_bug.cgi?id=8221>.
+  // Saying |do_QueryInterface()| on a pointer that is not otherwise owned by
+  // someone else is an automatic leak. See bug 8221.
 }
 
 template<class T>
 inline void
 do_QueryInterface(already_AddRefed<T>&, nsresult*)
 {
   // This signature exists solely to _stop_ you from doing the bad thing.
-  //  Saying |do_QueryInterface()| on a pointer that is not otherwise owned by
-  //  someone else is an automatic leak.  See <http://bugzilla.mozilla.org/show_bug.cgi?id=8221>.
+  // Saying |do_QueryInterface()| on a pointer that is not otherwise owned by
+  // someone else is an automatic leak. See bug 8221.
 }
 
 
 ////////////////////////////////////////////////////////////////////////////
 // Using servicemanager with COMPtrs
 class NS_COM_GLUE nsGetServiceByCID
 {
 public:
@@ -401,29 +402,26 @@ public:
 
   nsresult NS_FASTCALL operator()(const nsIID&, void**) const;
 
 private:
   const char* mContractID;
   nsresult* mErrorPtr;
 };
 
+/**
+ * Factors implementation for all template versions of nsCOMPtr.
+ *
+ * Here's the way people normally do things like this:
+ *
+ *   template<class T> class Foo { ... };
+ *   template<> class Foo<void*> { ... };
+ *   template<class T> class Foo<T*> : private Foo<void*> { ... };
+ */
 class nsCOMPtr_base
-/*
-  ...factors implementation for all template versions of |nsCOMPtr|.
-
-  This should really be an |nsCOMPtr<nsISupports>|, but this wouldn't work
-  because unlike the
-
-  Here's the way people normally do things like this
-
-    template<class T> class Foo { ... };
-    template<> class Foo<void*> { ... };
-    template<class T> class Foo<T*> : private Foo<void*> { ... };
-*/
 {
 public:
   explicit nsCOMPtr_base(nsISupports* aRawPtr = 0) : mRawPtr(aRawPtr) {}
 
   NS_COM_GLUE NS_CONSTRUCTOR_FASTCALL ~nsCOMPtr_base()
   {
     NSCAP_LOG_RELEASE(this, mRawPtr);
     if (mRawPtr) {
@@ -451,24 +449,22 @@ public:
   NS_COM_GLUE void** NS_FASTCALL
   begin_assignment();
 
 protected:
   NS_MAY_ALIAS_PTR(nsISupports) mRawPtr;
 
   void assign_assuming_AddRef(nsISupports* aNewPtr)
   {
-    /*
-      |AddRef()|ing the new value (before entering this function) before
-      |Release()|ing the old lets us safely ignore the self-assignment case.
-      We must, however, be careful only to |Release()| _after_ doing the
-      assignment, in case the |Release()| leads to our _own_ destruction,
-      which would, in turn, cause an incorrect second |Release()| of our old
-      pointer.  Thank <waterson@netscape.com> for discovering this.
-    */
+    // |AddRef()|ing the new value (before entering this function) before
+    // |Release()|ing the old lets us safely ignore the self-assignment case.
+    // We must, however, be careful only to |Release()| _after_ doing the
+    // assignment, in case the |Release()| leads to our _own_ destruction,
+    // which would, in turn, cause an incorrect second |Release()| of our old
+    // pointer. Thank <waterson@netscape.com> for discovering this.
     nsISupports* oldPtr = mRawPtr;
     mRawPtr = aNewPtr;
     NSCAP_LOG_ASSIGNMENT(this, aNewPtr);
     NSCAP_LOG_RELEASE(this, oldPtr);
     if (oldPtr) {
       NSCAP_RELEASE(this, oldPtr);
     }
   }
@@ -543,304 +539,294 @@ public:
   #define NSCAP_ASSERT_NO_QUERY_NEEDED()
 #endif
 
 
   // Constructors
 
   nsCOMPtr()
     : NSCAP_CTOR_BASE(0)
-    // default constructor
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
   }
 
   nsCOMPtr(const nsCOMPtr<T>& aSmartPtr)
     : NSCAP_CTOR_BASE(aSmartPtr.mRawPtr)
-    // copy-constructor
   {
     if (mRawPtr) {
       NSCAP_ADDREF(this, mRawPtr);
     }
     NSCAP_LOG_ASSIGNMENT(this, aSmartPtr.mRawPtr);
   }
 
   MOZ_IMPLICIT nsCOMPtr(T* aRawPtr)
     : NSCAP_CTOR_BASE(aRawPtr)
-    // construct from a raw pointer (of the right type)
   {
     if (mRawPtr) {
       NSCAP_ADDREF(this, mRawPtr);
     }
     NSCAP_LOG_ASSIGNMENT(this, aRawPtr);
     NSCAP_ASSERT_NO_QUERY_NEEDED();
   }
 
   MOZ_IMPLICIT nsCOMPtr(already_AddRefed<T>& aSmartPtr)
     : NSCAP_CTOR_BASE(aSmartPtr.take())
-    // construct from |already_AddRefed|
   {
     NSCAP_LOG_ASSIGNMENT(this, mRawPtr);
     NSCAP_ASSERT_NO_QUERY_NEEDED();
   }
 
+  // Construct from |otherComPtr.forget()|.
   MOZ_IMPLICIT nsCOMPtr(already_AddRefed<T>&& aSmartPtr)
     : NSCAP_CTOR_BASE(aSmartPtr.take())
-    // construct from |otherComPtr.forget()|
   {
     NSCAP_LOG_ASSIGNMENT(this, mRawPtr);
     NSCAP_ASSERT_NO_QUERY_NEEDED();
   }
 
+  // Construct from |already_AddRefed|.
   template<typename U>
   MOZ_IMPLICIT nsCOMPtr(already_AddRefed<U>& aSmartPtr)
     : NSCAP_CTOR_BASE(static_cast<T*>(aSmartPtr.take()))
-    // construct from |already_AddRefed|
   {
-    // But make sure that U actually inherits from T
+    // But make sure that U actually inherits from T.
     static_assert(mozilla::IsBaseOf<T, U>::value,
                   "U is not a subclass of T");
     NSCAP_LOG_ASSIGNMENT(this, static_cast<T*>(mRawPtr));
     NSCAP_ASSERT_NO_QUERY_NEEDED();
   }
 
+  // Construct from |otherComPtr.forget()|.
   template<typename U>
   MOZ_IMPLICIT nsCOMPtr(already_AddRefed<U>&& aSmartPtr)
     : NSCAP_CTOR_BASE(static_cast<T*>(aSmartPtr.take()))
-    // construct from |otherComPtr.forget()|
   {
-    // But make sure that U actually inherits from T
+    // But make sure that U actually inherits from T.
     static_assert(mozilla::IsBaseOf<T, U>::value,
                   "U is not a subclass of T");
     NSCAP_LOG_ASSIGNMENT(this, static_cast<T*>(mRawPtr));
     NSCAP_ASSERT_NO_QUERY_NEEDED();
   }
 
+  // Construct from |do_QueryInterface(expr)|.
   MOZ_IMPLICIT nsCOMPtr(const nsQueryInterface aQI)
     : NSCAP_CTOR_BASE(0)
-    // construct from |do_QueryInterface(expr)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_qi(aQI, NS_GET_TEMPLATE_IID(T));
   }
 
+  // Construct from |do_QueryInterface(expr, &rv)|.
   MOZ_IMPLICIT nsCOMPtr(const nsQueryInterfaceWithError& aQI)
     : NSCAP_CTOR_BASE(0)
-    // construct from |do_QueryInterface(expr, &rv)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_qi_with_error(aQI, NS_GET_TEMPLATE_IID(T));
   }
 
+  // Construct from |do_GetService(cid_expr)|.
   MOZ_IMPLICIT nsCOMPtr(const nsGetServiceByCID aGS)
     : NSCAP_CTOR_BASE(0)
-    // construct from |do_GetService(cid_expr)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_gs_cid(aGS, NS_GET_TEMPLATE_IID(T));
   }
 
+  // Construct from |do_GetService(cid_expr, &rv)|.
   MOZ_IMPLICIT nsCOMPtr(const nsGetServiceByCIDWithError& aGS)
     : NSCAP_CTOR_BASE(0)
-    // construct from |do_GetService(cid_expr, &rv)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_gs_cid_with_error(aGS, NS_GET_TEMPLATE_IID(T));
   }
 
+  // Construct from |do_GetService(contractid_expr)|.
   MOZ_IMPLICIT nsCOMPtr(const nsGetServiceByContractID aGS)
     : NSCAP_CTOR_BASE(0)
-    // construct from |do_GetService(contractid_expr)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_gs_contractid(aGS, NS_GET_TEMPLATE_IID(T));
   }
 
+  // Construct from |do_GetService(contractid_expr, &rv)|.
   MOZ_IMPLICIT nsCOMPtr(const nsGetServiceByContractIDWithError& aGS)
     : NSCAP_CTOR_BASE(0)
-    // construct from |do_GetService(contractid_expr, &rv)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_gs_contractid_with_error(aGS, NS_GET_TEMPLATE_IID(T));
   }
 
+  // And finally, anything else we might need to construct from can exploit the
+  // nsCOMPtr_helper facility.
   MOZ_IMPLICIT nsCOMPtr(const nsCOMPtr_helper& aHelper)
     : NSCAP_CTOR_BASE(0)
-    // ...and finally, anything else we might need to construct from
-    //  can exploit the |nsCOMPtr_helper| facility
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_helper(aHelper, NS_GET_TEMPLATE_IID(T));
     NSCAP_ASSERT_NO_QUERY_NEEDED();
   }
 
 
   // Assignment operators
 
   nsCOMPtr<T>& operator=(const nsCOMPtr<T>& aRhs)
-  // copy assignment operator
   {
     assign_with_AddRef(aRhs.mRawPtr);
     return *this;
   }
 
   nsCOMPtr<T>& operator=(T* aRhs)
-  // assign from a raw pointer (of the right type)
   {
     assign_with_AddRef(aRhs);
     NSCAP_ASSERT_NO_QUERY_NEEDED();
     return *this;
   }
 
+  // Assign from |already_AddRefed|.
   template<typename U>
   nsCOMPtr<T>& operator=(already_AddRefed<U>& aRhs)
-  // assign from |already_AddRefed|
   {
     // Make sure that U actually inherits from T
     static_assert(mozilla::IsBaseOf<T, U>::value,
                   "U is not a subclass of T");
     assign_assuming_AddRef(static_cast<T*>(aRhs.take()));
     NSCAP_ASSERT_NO_QUERY_NEEDED();
     return *this;
   }
 
+  // Assign from |otherComPtr.forget()|.
   template<typename U>
-  nsCOMPtr<T>& operator=(already_AddRefed<U> && aRhs)
-  // assign from |otherComPtr.forget()|
+  nsCOMPtr<T>& operator=(already_AddRefed<U>&& aRhs)
   {
     // Make sure that U actually inherits from T
     static_assert(mozilla::IsBaseOf<T, U>::value,
                   "U is not a subclass of T");
     assign_assuming_AddRef(static_cast<T*>(aRhs.take()));
     NSCAP_ASSERT_NO_QUERY_NEEDED();
     return *this;
   }
 
+  // Assign from |do_QueryInterface(expr)|.
   nsCOMPtr<T>& operator=(const nsQueryInterface aRhs)
-  // assign from |do_QueryInterface(expr)|
   {
     assign_from_qi(aRhs, NS_GET_TEMPLATE_IID(T));
     return *this;
   }
 
+  // Assign from |do_QueryInterface(expr, &rv)|.
   nsCOMPtr<T>& operator=(const nsQueryInterfaceWithError& aRhs)
-  // assign from |do_QueryInterface(expr, &rv)|
   {
     assign_from_qi_with_error(aRhs, NS_GET_TEMPLATE_IID(T));
     return *this;
   }
 
+  // Assign from |do_GetService(cid_expr)|.
   nsCOMPtr<T>& operator=(const nsGetServiceByCID aRhs)
-  // assign from |do_GetService(cid_expr)|
   {
     assign_from_gs_cid(aRhs, NS_GET_TEMPLATE_IID(T));
     return *this;
   }
 
+  // Assign from |do_GetService(cid_expr, &rv)|.
   nsCOMPtr<T>& operator=(const nsGetServiceByCIDWithError& aRhs)
-  // assign from |do_GetService(cid_expr, &rv)|
   {
     assign_from_gs_cid_with_error(aRhs, NS_GET_TEMPLATE_IID(T));
     return *this;
   }
 
+  // Assign from |do_GetService(contractid_expr)|.
   nsCOMPtr<T>& operator=(const nsGetServiceByContractID aRhs)
-  // assign from |do_GetService(contractid_expr)|
   {
     assign_from_gs_contractid(aRhs, NS_GET_TEMPLATE_IID(T));
     return *this;
   }
 
+  // Assign from |do_GetService(contractid_expr, &rv)|.
   nsCOMPtr<T>& operator=(const nsGetServiceByContractIDWithError& aRhs)
-  // assign from |do_GetService(contractid_expr, &rv)|
   {
     assign_from_gs_contractid_with_error(aRhs, NS_GET_TEMPLATE_IID(T));
     return *this;
   }
 
+  // And finally, anything else we might need to assign from can exploit the
+  // nsCOMPtr_helper facility.
   nsCOMPtr<T>& operator=(const nsCOMPtr_helper& aRhs)
-  // ...and finally, anything else we might need to assign from
-  //  can exploit the |nsCOMPtr_helper| facility.
   {
     assign_from_helper(aRhs, NS_GET_TEMPLATE_IID(T));
     NSCAP_ASSERT_NO_QUERY_NEEDED();
     return *this;
   }
 
+  // Exchange ownership with |aRhs|; can save a pair of refcount operations.
   void swap(nsCOMPtr<T>& aRhs)
-  // ...exchange ownership with |aRhs|; can save a pair of refcount operations
   {
 #ifdef NSCAP_FEATURE_USE_BASE
     nsISupports* temp = aRhs.mRawPtr;
 #else
     T* temp = aRhs.mRawPtr;
 #endif
     NSCAP_LOG_ASSIGNMENT(&aRhs, mRawPtr);
     NSCAP_LOG_ASSIGNMENT(this, temp);
     NSCAP_LOG_RELEASE(this, mRawPtr);
     NSCAP_LOG_RELEASE(&aRhs, temp);
     aRhs.mRawPtr = mRawPtr;
     mRawPtr = temp;
     // |aRhs| maintains the same invariants, so we don't need to |NSCAP_ASSERT_NO_QUERY_NEEDED|
   }
 
+  // Exchange ownership with |aRhs|; can save a pair of refcount operations.
   void swap(T*& aRhs)
-  // ...exchange ownership with |aRhs|; can save a pair of refcount operations
   {
 #ifdef NSCAP_FEATURE_USE_BASE
     nsISupports* temp = aRhs;
 #else
     T* temp = aRhs;
 #endif
     NSCAP_LOG_ASSIGNMENT(this, temp);
     NSCAP_LOG_RELEASE(this, mRawPtr);
     aRhs = reinterpret_cast<T*>(mRawPtr);
     mRawPtr = temp;
     NSCAP_ASSERT_NO_QUERY_NEEDED();
   }
 
 
   // Other pointer operators
 
+  // Return the value of mRawPtr and null out mRawPtr. Useful for
+  // already_AddRefed return values.
   already_AddRefed<T> forget()
-  // return the value of mRawPtr and null out mRawPtr. Useful for
-  // already_AddRefed return values.
   {
     T* temp = 0;
     swap(temp);
     return already_AddRefed<T>(temp);
   }
 
+  // Set the target of aRhs to the value of mRawPtr and null out mRawPtr.
+  // Useful to avoid unnecessary AddRef/Release pairs with "out" parameters
+  // where aRhs bay be a T** or an I** where I is a base class of T.
   template<typename I>
   void forget(I** aRhs)
-  // Set the target of aRhs to the value of mRawPtr and null out mRawPtr.
-  // Useful to avoid unnecessary AddRef/Release pairs with "out"
-  // parameters where aRhs bay be a T** or an I** where I is a base class
-  // of T.
   {
     NS_ASSERTION(aRhs, "Null pointer passed to forget!");
     NSCAP_LOG_RELEASE(this, mRawPtr);
     *aRhs = get();
     mRawPtr = 0;
   }
 
-  /*
-    Prefer the implicit conversion provided automatically by |operator T*() const|.
-    Use |get()| to resolve ambiguity or to get a castable pointer.
-  */
+  // Prefer the implicit conversion provided automatically by
+  // |operator T*() const|. Use |get()| to resolve ambiguity or to get a
+  // castable pointer.
   T* get() const { return reinterpret_cast<T*>(mRawPtr); }
 
-  /*
-    Makes an |nsCOMPtr| act like its underlying raw pointer type whenever it
-    is used in a context where a raw pointer is expected.  It is this operator
-    that makes an |nsCOMPtr| substitutable for a raw pointer.
-
-    Prefer the implicit use of this operator to calling |get()|, except where
-    necessary to resolve ambiguity.
-  */
+  // Makes an nsCOMPtr act like its underlying raw pointer type whenever it is
+  // used in a context where a raw pointer is expected. It is this operator
+  // that makes an nsCOMPtr substitutable for a raw pointer.
+  //
+  // Prefer the implicit use of this operator to calling |get()|, except where
+  // necessary to resolve ambiguity.
   operator T*() const { return get(); }
 
   T* operator->() const
   {
     NS_ABORT_IF_FALSE(mRawPtr != 0,
                       "You can't dereference a NULL nsCOMPtr with operator->().");
     return get();
   }
@@ -864,273 +850,263 @@ public:
 #else
     assign_assuming_AddRef(0);
     return reinterpret_cast<T**>(&mRawPtr);
 #endif
   }
 };
 
 
-
 /*
-  Specializing |nsCOMPtr| for |nsISupports| allows us to use |nsCOMPtr<nsISupports>| the
-  same way people use |nsISupports*| and |void*|, i.e., as a `catch-all' pointer pointing
-  to any valid [XP]COM interface.  Otherwise, an |nsCOMPtr<nsISupports>| would only be able
-  to point to the single [XP]COM-correct |nsISupports| instance within an object; extra
-  querying ensues.  Clients need to be able to pass around arbitrary interface pointers,
-  without hassles, through intermediary code that doesn't know the exact type.
-*/
-
+ * Specializing nsCOMPtr for nsISupports allows us to use nsCOMPtr<nsISupports>
+ * the same way people use nsISupports* and void*, i.e., as a `catch-all'
+ * pointing to any valid [XP]COM interface. Otherwise, an nsCOMPtr<nsISupports>
+ * would only be able to point to the single [XP]COM-correct nsISupports
+ * instance within an object; extra querying ensues. Clients need to be able to
+ * pass around arbitrary interface pointers, without hassles, through
+ * intermediary code that doesn't know the exact type.
+ */
 template<>
 class nsCOMPtr<nsISupports>
   : private nsCOMPtr_base
 {
 public:
   typedef nsISupports element_type;
 
   // Constructors
 
   nsCOMPtr()
     : nsCOMPtr_base(0)
-    // default constructor
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
   }
 
   nsCOMPtr(const nsCOMPtr<nsISupports>& aSmartPtr)
     : nsCOMPtr_base(aSmartPtr.mRawPtr)
-    // copy constructor
   {
     if (mRawPtr) {
       NSCAP_ADDREF(this, mRawPtr);
     }
     NSCAP_LOG_ASSIGNMENT(this, aSmartPtr.mRawPtr);
   }
 
   MOZ_IMPLICIT nsCOMPtr(nsISupports* aRawPtr)
     : nsCOMPtr_base(aRawPtr)
-    // construct from a raw pointer (of the right type)
   {
     if (mRawPtr) {
       NSCAP_ADDREF(this, mRawPtr);
     }
     NSCAP_LOG_ASSIGNMENT(this, aRawPtr);
   }
 
+  // Construct from |already_AddRefed|.
   MOZ_IMPLICIT nsCOMPtr(already_AddRefed<nsISupports>& aSmartPtr)
     : nsCOMPtr_base(aSmartPtr.take())
-    // construct from |already_AddRefed|
   {
     NSCAP_LOG_ASSIGNMENT(this, mRawPtr);
   }
 
+  // Construct from |otherComPtr.forget()|.
   MOZ_IMPLICIT nsCOMPtr(already_AddRefed<nsISupports>&& aSmartPtr)
     : nsCOMPtr_base(aSmartPtr.take())
-    // construct from |otherComPtr.forget()|
   {
     NSCAP_LOG_ASSIGNMENT(this, mRawPtr);
   }
 
+  // Construct from |do_QueryInterface(expr)|.
   MOZ_IMPLICIT nsCOMPtr(const nsQueryInterface aQI)
     : nsCOMPtr_base(0)
-    // assign from |do_QueryInterface(expr)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_qi(aQI, NS_GET_IID(nsISupports));
   }
 
+  // Construct from |do_QueryInterface(expr, &rv)|.
   MOZ_IMPLICIT nsCOMPtr(const nsQueryInterfaceWithError& aQI)
     : nsCOMPtr_base(0)
-    // assign from |do_QueryInterface(expr, &rv)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_qi_with_error(aQI, NS_GET_IID(nsISupports));
   }
 
+  // Construct from |do_GetService(cid_expr)|.
   MOZ_IMPLICIT nsCOMPtr(const nsGetServiceByCID aGS)
     : nsCOMPtr_base(0)
-    // assign from |do_GetService(cid_expr)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_gs_cid(aGS, NS_GET_IID(nsISupports));
   }
 
+  // Construct from |do_GetService(cid_expr, &rv)|.
   MOZ_IMPLICIT nsCOMPtr(const nsGetServiceByCIDWithError& aGS)
     : nsCOMPtr_base(0)
-    // assign from |do_GetService(cid_expr, &rv)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_gs_cid_with_error(aGS, NS_GET_IID(nsISupports));
   }
 
+  // Construct from |do_GetService(contractid_expr)|.
   MOZ_IMPLICIT nsCOMPtr(const nsGetServiceByContractID aGS)
     : nsCOMPtr_base(0)
-    // assign from |do_GetService(contractid_expr)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_gs_contractid(aGS, NS_GET_IID(nsISupports));
   }
 
+  // Construct from |do_GetService(contractid_expr, &rv)|.
   MOZ_IMPLICIT nsCOMPtr(const nsGetServiceByContractIDWithError& aGS)
     : nsCOMPtr_base(0)
-    // assign from |do_GetService(contractid_expr, &rv)|
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_gs_contractid_with_error(aGS, NS_GET_IID(nsISupports));
   }
 
+  // And finally, anything else we might need to construct from can exploit
+  // the |nsCOMPtr_helper| facility
   MOZ_IMPLICIT nsCOMPtr(const nsCOMPtr_helper& aHelper)
     : nsCOMPtr_base(0)
-    // ...and finally, anything else we might need to construct from
-    //  can exploit the |nsCOMPtr_helper| facility
   {
     NSCAP_LOG_ASSIGNMENT(this, 0);
     assign_from_helper(aHelper, NS_GET_IID(nsISupports));
   }
 
 
   // Assignment operators
 
   nsCOMPtr<nsISupports>& operator=(const nsCOMPtr<nsISupports>& aRhs)
-  // copy assignment operator
   {
     assign_with_AddRef(aRhs.mRawPtr);
     return *this;
   }
 
   nsCOMPtr<nsISupports>& operator=(nsISupports* aRhs)
-  // assign from a raw pointer (of the right type)
   {
     assign_with_AddRef(aRhs);
     return *this;
   }
 
+  // Assign from |already_AddRefed|.
   nsCOMPtr<nsISupports>& operator=(already_AddRefed<nsISupports>& aRhs)
-  // assign from |already_AddRefed|
   {
     assign_assuming_AddRef(aRhs.take());
     return *this;
   }
 
-  nsCOMPtr<nsISupports>& operator=(already_AddRefed<nsISupports> && aRhs)
-  // assign from |otherComPtr.forget()|
+  // Assign from |otherComPtr.forget()|.
+  nsCOMPtr<nsISupports>& operator=(already_AddRefed<nsISupports>&& aRhs)
   {
     assign_assuming_AddRef(aRhs.take());
     return *this;
   }
 
+  // Assign from |do_QueryInterface(expr)|.
   nsCOMPtr<nsISupports>& operator=(const nsQueryInterface aRhs)
-  // assign from |do_QueryInterface(expr)|
   {
     assign_from_qi(aRhs, NS_GET_IID(nsISupports));
     return *this;
   }
 
+  // Assign from |do_QueryInterface(expr, &rv)|.
   nsCOMPtr<nsISupports>& operator=(const nsQueryInterfaceWithError& aRhs)
-  // assign from |do_QueryInterface(expr, &rv)|
   {
     assign_from_qi_with_error(aRhs, NS_GET_IID(nsISupports));
     return *this;
   }
 
+  // Assign from |do_GetService(cid_expr)|.
   nsCOMPtr<nsISupports>& operator=(const nsGetServiceByCID aRhs)
-  // assign from |do_GetService(cid_expr)|
   {
     assign_from_gs_cid(aRhs, NS_GET_IID(nsISupports));
     return *this;
   }
 
+  // Assign from |do_GetService(cid_expr, &rv)|.
   nsCOMPtr<nsISupports>& operator=(const nsGetServiceByCIDWithError& aRhs)
-  // assign from |do_GetService(cid_expr, &rv)|
   {
     assign_from_gs_cid_with_error(aRhs, NS_GET_IID(nsISupports));
     return *this;
   }
 
+  // Assign from |do_GetService(contractid_expr)|.
   nsCOMPtr<nsISupports>& operator=(const nsGetServiceByContractID aRhs)
-  // assign from |do_GetService(contractid_expr)|
   {
     assign_from_gs_contractid(aRhs, NS_GET_IID(nsISupports));
     return *this;
   }
 
+  // Assign from |do_GetService(contractid_expr, &rv)|.
   nsCOMPtr<nsISupports>& operator=(const nsGetServiceByContractIDWithError& aRhs)
-  // assign from |do_GetService(contractid_expr, &rv)|
   {
     assign_from_gs_contractid_with_error(aRhs, NS_GET_IID(nsISupports));
     return *this;
   }
 
+  // And finally, anything else we might need to assign from can exploit the
+  // nsCOMPtr_helper facility
   nsCOMPtr<nsISupports>& operator=(const nsCOMPtr_helper& aRhs)
-  // ...and finally, anything else we might need to assign from
-  //  can exploit the |nsCOMPtr_helper| facility.
   {
     assign_from_helper(aRhs, NS_GET_IID(nsISupports));
     return *this;
   }
 
+  // Exchange ownership with |aRhs|; can save a pair of refcount operations.
   void swap(nsCOMPtr<nsISupports>& aRhs)
-  // ...exchange ownership with |aRhs|; can save a pair of refcount operations
   {
     nsISupports* temp = aRhs.mRawPtr;
     NSCAP_LOG_ASSIGNMENT(&aRhs, mRawPtr);
     NSCAP_LOG_ASSIGNMENT(this, temp);
     NSCAP_LOG_RELEASE(this, mRawPtr);
     NSCAP_LOG_RELEASE(&aRhs, temp);
     aRhs.mRawPtr = mRawPtr;
     mRawPtr = temp;
   }
 
+  // Exchange ownership with |aRhs|; can save a pair of refcount operations.
   void swap(nsISupports*& aRhs)
-  // ...exchange ownership with |aRhs|; can save a pair of refcount operations
   {
     nsISupports* temp = aRhs;
     NSCAP_LOG_ASSIGNMENT(this, temp);
     NSCAP_LOG_RELEASE(this, mRawPtr);
     aRhs = mRawPtr;
     mRawPtr = temp;
   }
 
+  // Return the value of mRawPtr and null out mRawPtr. Useful for
+  // already_AddRefed return values.
   already_AddRefed<nsISupports> forget()
-  // return the value of mRawPtr and null out mRawPtr. Useful for
-  // already_AddRefed return values.
   {
     nsISupports* temp = 0;
     swap(temp);
     return already_AddRefed<nsISupports>(temp);
   }
 
-  void forget(nsISupports** aRhs)
   // Set the target of aRhs to the value of mRawPtr and null out mRawPtr.
   // Useful to avoid unnecessary AddRef/Release pairs with "out"
   // parameters.
+  void forget(nsISupports** aRhs)
   {
     NS_ASSERTION(aRhs, "Null pointer passed to forget!");
     *aRhs = 0;
     swap(*aRhs);
   }
 
   // Other pointer operators
 
-  /*
-    Prefer the implicit conversion provided automatically by
-    |operator nsISupports*() const|.
-    Use |get()| to resolve ambiguity or to get a castable pointer.
-  */
+  // Prefer the implicit conversion provided automatically by
+  // |operator nsISupports*() const|. Use |get()| to resolve ambiguity or to
+  // get a castable pointer.
   nsISupports* get() const { return reinterpret_cast<nsISupports*>(mRawPtr); }
 
-  /*
-    Makes an |nsCOMPtr| act like its underlying raw pointer type whenever it
-    is used in a context where a raw pointer is expected.  It is this operator
-    that makes an |nsCOMPtr| substitutable for a raw pointer.
-
-    Prefer the implicit use of this operator to calling |get()|, except where
-    necessary to resolve ambiguity.
-  */
-  operator nsISupports*() const { return get(); }
+  // Makes an nsCOMPtr act like its underlying raw pointer type whenever it is
+  // used in a context where a raw pointer is expected. It is this operator
+  // that makes an nsCOMPtr substitutable for a raw pointer.
+  //
+  // Prefer the implicit use of this operator to calling |get()|, except where
+  // necessary to resolve ambiguity/
+  operator nsISupports* () const { return get(); }
 
   nsISupports* operator->() const
   {
     NS_ABORT_IF_FALSE(mRawPtr != 0,
                       "You can't dereference a NULL nsCOMPtr with operator->().");
     return get();
   }
 
@@ -1291,35 +1267,33 @@ address_of(nsCOMPtr<T>& aPtr)
 
 template<class T>
 inline const nsCOMPtr<T>*
 address_of(const nsCOMPtr<T>& aPtr)
 {
   return aPtr.get_address();
 }
 
+/**
+ * This class is designed to be used for anonymous temporary objects in the
+ * argument list of calls that return COM interface pointers, e.g.,
+ *
+ *   nsCOMPtr<IFoo> fooP;
+ *   ...->QueryInterface(iid, getter_AddRefs(fooP))
+ *
+ * DO NOT USE THIS TYPE DIRECTLY IN YOUR CODE. Use |getter_AddRefs()| instead.
+ *
+ * When initialized with a |nsCOMPtr|, as in the example above, it returns
+ * a |void**|, a |T**|, or an |nsISupports**| as needed, that the outer call
+ * (|QueryInterface| in this case) can fill in.
+ *
+ * This type should be a nested class inside |nsCOMPtr<T>|.
+ */
 template<class T>
 class nsGetterAddRefs
-/*
-  ...
-
-  This class is designed to be used for anonymous temporary objects in the
-  argument list of calls that return COM interface pointers, e.g.,
-
-    nsCOMPtr<IFoo> fooP;
-    ...->QueryInterface(iid, getter_AddRefs(fooP))
-
-  DO NOT USE THIS TYPE DIRECTLY IN YOUR CODE.  Use |getter_AddRefs()| instead.
-
-  When initialized with a |nsCOMPtr|, as in the example above, it returns
-  a |void**|, a |T**|, or an |nsISupports**| as needed, that the outer call (|QueryInterface| in this
-  case) can fill in.
-
-  This type should be a nested class inside |nsCOMPtr<T>|.
-*/
 {
 public:
   explicit nsGetterAddRefs(nsCOMPtr<T>& aSmartPtr)
     : mTargetSmartPtr(aSmartPtr)
   {
   }
 
 #if defined(NSCAP_FEATURE_TEST_DONTQUERY_CASES) || defined(NSCAP_LOG_EXTERNAL_ASSIGNMENT)
@@ -1373,24 +1347,19 @@ public:
 
   operator nsISupports**() { return mTargetSmartPtr.StartAssignment(); }
   nsISupports*& operator*() { return *(mTargetSmartPtr.StartAssignment()); }
 
 private:
   nsCOMPtr<nsISupports>& mTargetSmartPtr;
 };
 
-
 template<class T>
 inline nsGetterAddRefs<T>
 getter_AddRefs(nsCOMPtr<T>& aSmartPtr)
-/*
-  Used around a |nsCOMPtr| when
-  ...makes the class |nsGetterAddRefs<T>| invisible.
-*/
 {
   return nsGetterAddRefs<T>(aSmartPtr);
 }
 
 template<class T, class DestinationType>
 inline nsresult
 CallQueryInterface(T* aSource, nsGetterAddRefs<DestinationType> aDestination)
 {
@@ -1476,66 +1445,66 @@ operator!=(U* aLhs, const nsCOMPtr<T>& a
 }
 
 
 
 // Comparing an |nsCOMPtr| to |0|
 
 class NSCAP_Zero;
 
+// Specifically to allow |smartPtr == 0|.
 template<class T>
 inline bool
 operator==(const nsCOMPtr<T>& aLhs, NSCAP_Zero* aRhs)
-// specifically to allow |smartPtr == 0|
 {
   return static_cast<const void*>(aLhs.get()) == reinterpret_cast<const void*>(aRhs);
 }
 
+// Specifically to allow |0 == smartPtr|.
 template<class T>
 inline bool
 operator==(NSCAP_Zero* aLhs, const nsCOMPtr<T>& aRhs)
-// specifically to allow |0 == smartPtr|
 {
   return reinterpret_cast<const void*>(aLhs) == static_cast<const void*>(aRhs.get());
 }
 
+// Specifically to allow |smartPtr != 0|.
 template<class T>
 inline bool
 operator!=(const nsCOMPtr<T>& aLhs, NSCAP_Zero* aRhs)
-// specifically to allow |smartPtr != 0|
 {
   return static_cast<const void*>(aLhs.get()) != reinterpret_cast<const void*>(aRhs);
 }
 
+// Specifically to allow |0 != smartPtr|.
 template<class T>
 inline bool
 operator!=(NSCAP_Zero* aLhs, const nsCOMPtr<T>& aRhs)
-// specifically to allow |0 != smartPtr|
 {
   return reinterpret_cast<const void*>(aLhs) != static_cast<const void*>(aRhs.get());
 }
 
 
 #ifdef HAVE_CPP_TROUBLE_COMPARING_TO_ZERO
 
 // We need to explicitly define comparison operators for `int'
 // because the compiler is lame.
 
+// Specifically to allow |smartPtr == 0|.
 template<class T>
 inline bool
 operator==(const nsCOMPtr<T>& lhs, int rhs)
-// specifically to allow |smartPtr == 0|
 {
   return static_cast<const void*>(lhs.get()) == reinterpret_cast<const void*>(rhs);
 }
 
+// Specifically to allow |0 == smartPtr|.
 template<class T>
 inline bool
 operator==(int lhs, const nsCOMPtr<T>& rhs)
-// specifically to allow |0 == smartPtr|
 {
   return reinterpret_cast<const void*>(lhs) == static_cast<const void*>(rhs.get());
 }
 
 #endif // !defined(HAVE_CPP_TROUBLE_COMPARING_TO_ZERO)
 
 // Comparing any two [XP]COM objects for identity