Format include/base comments for Doxygen (see issue #3384)

include/base/cef_scoped_refptr.h

@@ -142,68 +142,76 @@ scoped_refptr<T> WrapRefCounted(T* t) {
 
 }  // namespace base
 
-//
-// A smart pointer class for reference counted objects.  Use this class instead
-// of calling AddRef and Release manually on a reference counted object to
-// avoid common memory leaks caused by forgetting to Release an object
-// reference.  Sample usage:
-//
-//   class MyFoo : public RefCounted<MyFoo> {
-//    ...
-//    private:
-//     friend class RefCounted<MyFoo>;  // Allow destruction by RefCounted<>.
-//     ~MyFoo();                        // Destructor must be private/protected.
-//   };
-//
-//   void some_function() {
-//     scoped_refptr<MyFoo> foo = MakeRefCounted<MyFoo>();
-//     foo->Method(param);
-//     // |foo| is released when this function returns
-//   }
-//
-//   void some_other_function() {
-//     scoped_refptr<MyFoo> foo = MakeRefCounted<MyFoo>();
-//     ...
-//     foo.reset();  // explicitly releases |foo|
-//     ...
-//     if (foo)
-//       foo->Method(param);
-//   }
-//
-// The above examples show how scoped_refptr<T> acts like a pointer to T.
-// Given two scoped_refptr<T> classes, it is also possible to exchange
-// references between the two objects, like so:
-//
-//   {
-//     scoped_refptr<MyFoo> a = MakeRefCounted<MyFoo>();
-//     scoped_refptr<MyFoo> b;
-//
-//     b.swap(a);
-//     // now, |b| references the MyFoo object, and |a| references nullptr.
-//   }
-//
-// To make both |a| and |b| in the above example reference the same MyFoo
-// object, simply use the assignment operator:
-//
-//   {
-//     scoped_refptr<MyFoo> a = MakeRefCounted<MyFoo>();
-//     scoped_refptr<MyFoo> b;
-//
-//     b = a;
-//     // now, |a| and |b| each own a reference to the same MyFoo object.
-//   }
-//
-// Also see Chromium's ownership and calling conventions:
-// https://chromium.googlesource.com/chromium/src/+/lkgr/styleguide/c++/c++.md#object-ownership-and-calling-conventions
-// Specifically:
-//   If the function (at least sometimes) takes a ref on a refcounted object,
-//   declare the param as scoped_refptr<T>. The caller can decide whether it
-//   wishes to transfer ownership (by calling std::move(t) when passing t) or
-//   retain its ref (by simply passing t directly).
-//   In other words, use scoped_refptr like you would a std::unique_ptr except
-//   in the odd case where it's required to hold on to a ref while handing one
-//   to another component (if a component merely needs to use t on the stack
-//   without keeping a ref: pass t as a raw T*).
+///
+/// A smart pointer class for reference counted objects.  Use this class instead
+/// of calling AddRef and Release manually on a reference counted object to
+/// avoid common memory leaks caused by forgetting to Release an object
+/// reference. Sample usage:
+///
+/// <pre>
+///   class MyFoo : public RefCounted<MyFoo> {
+///    ...
+///    private:
+///     friend class RefCounted<MyFoo>;  // Allow destruction by RefCounted<>.
+///     ~MyFoo();                        // Destructor must be
+///     private/protected.
+///   };
+///
+///   void some_function() {
+///     scoped_refptr<MyFoo> foo = MakeRefCounted<MyFoo>();
+///     foo->Method(param);
+///     // |foo| is released when this function returns
+///   }
+///
+///   void some_other_function() {
+///     scoped_refptr<MyFoo> foo = MakeRefCounted<MyFoo>();
+///     ...
+///     foo.reset();  // explicitly releases |foo|
+///     ...
+///     if (foo)
+///       foo->Method(param);
+///   }
+/// </pre>
+///
+/// The above examples show how scoped_refptr<T> acts like a pointer to T.
+/// Given two scoped_refptr<T> classes, it is also possible to exchange
+/// references between the two objects, like so:
+///
+/// <pre>
+///   {
+///     scoped_refptr<MyFoo> a = MakeRefCounted<MyFoo>();
+///     scoped_refptr<MyFoo> b;
+///
+///     b.swap(a);
+///     // now, |b| references the MyFoo object, and |a| references nullptr.
+///   }
+/// </pre>
+///
+/// To make both |a| and |b| in the above example reference the same MyFoo
+/// object, simply use the assignment operator:
+///
+/// <pre>
+///   {
+///     scoped_refptr<MyFoo> a = MakeRefCounted<MyFoo>();
+///     scoped_refptr<MyFoo> b;
+///
+///     b = a;
+///     // now, |a| and |b| each own a reference to the same MyFoo object.
+///   }
+/// </pre>
+///
+/// Also see Chromium's ownership and calling conventions:
+/// https://chromium.googlesource.com/chromium/src/+/lkgr/styleguide/c++/c++.md#object-ownership-and-calling-conventions
+/// Specifically:
+///   If the function (at least sometimes) takes a ref on a refcounted object,
+///   declare the param as scoped_refptr<T>. The caller can decide whether it
+///   wishes to transfer ownership (by calling std::move(t) when passing t) or
+///   retain its ref (by simply passing t directly).
+///   In other words, use scoped_refptr like you would a std::unique_ptr except
+///   in the odd case where it's required to hold on to a ref while handing one
+///   to another component (if a component merely needs to use t on the stack
+///   without keeping a ref: pass t as a raw T*).
+///
 template <class T>
 class TRIVIAL_ABI scoped_refptr {
  public: