New C++ Docs.

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

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

4 files changed, 269 insertions, 148 deletions

diff --git a/ppapi/cpp/module.h b/ppapi/cpp/module.h
index 99526f0..a47cd26 100644
--- a/ppapi/cpp/module.h
+++ b/ppapi/cpp/module.h
@@ -1,4 +1,4 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
@@ -15,10 +15,17 @@
 #include "ppapi/c/ppb_core.h"
 #include "ppapi/cpp/core.h"
 
+
+/// @file
+/// This file defines a Module class.
 namespace pp {
 
 class Instance;
 
+/// The Module class.  The browser calls CreateInstance() to create
+/// an instance of your module on the web page.  The browser creates a new
+/// instance for each <code>\<embed></code> tag with
+/// <code>type="application/x-nacl"</code>
 class Module {
  public:
   typedef std::map<PP_Instance, Instance*> InstanceMap;
diff --git a/ppapi/cpp/module_embedder.h b/ppapi/cpp/module_embedder.h
index c384364..b7b7d43 100644
--- a/ppapi/cpp/module_embedder.h
+++ b/ppapi/cpp/module_embedder.h
@@ -1,18 +1,23 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef PPAPI_CPP_MODULE_EMBEDDER_H_
 #define PPAPI_CPP_MODULE_EMBEDDER_H_
 
+/// @file
+/// This file defines the APIs for creating a Module object.
 namespace pp {
 
 class Module;
-// Implemented by the embedder.
-//
-// Creates the pp::Module object associated with this plugin. Returns the
-// module if it was successfully created, or NULL on failure. Upon failure,
-// the plugin will be unloaded.
+
+/// This function creates the <code>pp::Module</code> object associated with
+/// this module.
+///
+/// <strong>Note: </strong>NaCl module developers must implement this function.
+///
+/// @return Returns the module if it was successfully created, or NULL on
+/// failure. Upon failure, the module will be unloaded.
 pp::Module* CreateModule();
 
 }  // namespace pp
diff --git a/ppapi/cpp/paint_aggregator.h b/ppapi/cpp/paint_aggregator.h
index dd994c1..85c4442 100644
--- a/ppapi/cpp/paint_aggregator.h
+++ b/ppapi/cpp/paint_aggregator.h
@@ -11,70 +11,108 @@
 #include "ppapi/cpp/point.h"
 #include "ppapi/cpp/rect.h"
 
+/// @file
+/// This file defines the API to aggregate multiple invalidation and scroll
+/// commands to produce a scroll and repaint sequence.
 namespace pp {
 
-// This class is responsible for aggregating multiple invalidation and scroll
-// commands to produce a scroll and repaint sequence. You can use this manually
-// to track your updates, but most applications will use the PaintManager to
-// additionally handle the necessary callbacks on top of the PaintAggregator
-// functionality.
-//
-// See http://code.google.com/p/ppapi/wiki/2DPaintingModel
+/// This class is responsible for aggregating multiple invalidation and scroll
+/// commands to produce a scroll and repaint sequence. You can use this manually
+/// to track your updates, but most applications will use the PaintManager to
+/// additionally handle the necessary callbacks on top of the PaintAggregator
+/// functionality.
+///
+/// See http://code.google.com/p/ppapi/wiki/2DPaintingModel
 class PaintAggregator {
  public:
   struct PaintUpdate {
+    /// Default constructor for creating an is_null() <code>PaintUpdate</code>
+    /// object.
     PaintUpdate();
+
+    /// Destructor.
     ~PaintUpdate();
 
-    // True if there is a scroll applied. This indicates that the scroll delta
-    // and scroll_rect are nonzero (just as a convenience).
+    /// True if there is a scroll applied. This indicates that the scroll delta
+    /// and scroll_rect are nonzero (just as a convenience).
     bool has_scroll;
 
-    // The amount to scroll by. Either the X or Y may be nonzero to indicate a
-    // scroll in that direction, but there will never be a scroll in both
-    // directions at the same time (this will be converted to a paint of the
-    // region instead).
-    //
-    // If there is no scroll, this will be (0, 0).
+    /// The amount to scroll by. Either the X or Y may be nonzero to indicate a
+    /// scroll in that direction, but there will never be a scroll in both
+    /// directions at the same time (this will be converted to a paint of the
+    /// region instead).
+    ///
+    /// If there is no scroll, this will be (0, 0).
     Point scroll_delta;
 
-    // The rectangle that should be scrolled by the scroll_delta. If there is no
-    // scroll, this will be (0, 0, 0, 0). We only track one scroll command at
-    // once. If there are multiple ones, they will be converted to invalidates.
+    /// The rectangle that should be scrolled by the scroll_delta. If there is
+    /// no scroll, this will be (0, 0, 0, 0). We only track one scroll command
+    /// at once. If there are multiple ones, they will be converted to
+    /// invalidates.
     Rect scroll_rect;
 
-    // A list of all the individual dirty rectangles. This is an aggregated list
-    // of all invalidate calls. Different rectangles may be unified to produce a
-    // minimal list with no overlap that is more efficient to paint. This list
-    // also contains the region exposed by any scroll command.
+    /// A list of all the individual dirty rectangles. This is an aggregated
+    /// list of all invalidate calls. Different rectangles may be unified to
+    /// produce a minimal list with no overlap that is more efficient to paint.
+    /// This list also contains the region exposed by any scroll command.
     std::vector<Rect> paint_rects;
 
-    // The union of all paint_rects.
+    /// The union of all paint_rects.
     Rect paint_bounds;
   };
 
+  /// Default constructor.
   PaintAggregator();
 
-  // Setters for the configuration settings. See the corresponding variables
-  // below for what these mean.
+  /// Setter function setting the max ratio of paint rect area to scroll rect
+  /// area that we will tolerate before downgrading the scroll into a repaint.
+  ///
+  /// If the combined area of paint rects contained within the scroll
+  /// rect grows too large, then we might as well just treat
+  /// the scroll rect as a paint rect.
+  ///
+  /// @param[in] area The max ratio of paint rect area to scroll rect area that
+  /// we will tolerate before downgrading the scroll into a repaint.
   void set_max_redundant_paint_to_scroll_area(float area) {
     max_redundant_paint_to_scroll_area_ = area;
   }
+
+  /// Setter function for setting the maximum number of paint rects. If we
+  /// exceed this limit, then we'll start combining paint rects (see
+  /// CombinePaintRects). This limiting can be important since there is
+  /// typically some overhead in deciding what to paint. If your module is fast
+  /// at doing these computations, raise this threshold, if your module is
+  /// slow, lower it (probably requires some tuning to find the right value).
+  ///
+  /// @param[in] max_rects The maximum number of paint rects.
   void set_max_paint_rects(size_t max_rects) {
     max_paint_rects_ = max_rects;
   }
 
-  // There is a PendingUpdate if InvalidateRect or ScrollRect were called and
-  // ClearPendingUpdate was not called.
+  /// This function determines if there is a pending update. There is a
+  /// PendingUpdate if InvalidateRect or ScrollRect were called and
+  /// ClearPendingUpdate was not called.
+  ///
+  /// @return True if there is a pending update, otherwise false.
   bool HasPendingUpdate() const;
+
+  /// This function clears a pending update.
   void ClearPendingUpdate();
 
+  /// This function gets a pending update.
+  ///
+  /// @return A PaintUpdate containing the pending update.
   PaintUpdate GetPendingUpdate() const;
 
-  // The given rect should be repainted.
+  /// This function invalidates the rect so it will be repainted.
+  ///
+  /// @param[in] rect A rect to be repainted.
   void InvalidateRect(const Rect& rect);
 
-  // The given rect should be scrolled by the given amounts.
+  /// This function adds a pending scroll update.
+  ///
+  /// @param[in] clip_rect The rect to scroll.
+  /// @param[in] amount A Point amount to scroll <code>rect</code>.
   void ScrollRect(const Rect& clip_rect, const Point& amount);
 
  private:
diff --git a/ppapi/cpp/paint_manager.h b/ppapi/cpp/paint_manager.h
index 5f14862..0943c37 100644
--- a/ppapi/cpp/paint_manager.h
+++ b/ppapi/cpp/paint_manager.h
@@ -1,4 +1,4 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
@@ -11,6 +11,10 @@
 #include "ppapi/cpp/graphics_2d.h"
 #include "ppapi/cpp/paint_aggregator.h"
 
+/// @file
+/// This file defines the API to convert the "plugin push" model of painting
+/// in PPAPI to a paint request at a later time.
+
 namespace pp {
 
 class Graphics2D;
@@ -18,69 +22,77 @@ class Instance;
 class Point;
 class Rect;
 
-// This class converts the "plugin push" model of painting in PPAPI to a paint
-// request at a later time. Usage is that you call Invalidate and Scroll, and
-// implement the Client interface. Your OnPaint handler will then get called
-// with coalesced paint events.
-//
-// This class is basically a PaintAggregator that groups updates, plus
-// management of callbacks for scheduling paints.
-//
-// Typical usage:
-//
-//  class MyClass : public pp::Instance, public PaintManager::Client {
-//   public:
-//    MyClass() {
-//      paint_manager_.Initialize(this, this, false);
-//    }
-//
-//    void ViewChanged(const pp::Rect& position, const pp::Rect& clip) {
-//      paint_manager_.SetSize(position.size());
-//    }
-//
-//    void DoSomething() {
-//      // This function does something like respond to an event that causes
-//      // the screen to need updating.
-//      paint_manager_.InvalidateRect(some_rect);
-//    }
-//
-//    // Implementation of PaintManager::Client
-//    virtual bool OnPaint(pp::Graphics2D& device,
-//                         const pp::PaintUpdate& update) {
-//      // If our app needed scrolling, we would apply that first here.
-//
-//      // Then we would either repaint the area returned by GetPaintBounds or
-//      // iterate through all the paint_rects.
-//
-//      // The caller will call Flush() for us, so don't do that here.
-//      return true;
-//    }
-//
-//   private:
-//    pp::PaintManager paint_manager_;
-//  };
+/// This class converts the "instance push" model of painting in PPAPI to a
+/// paint request at a later time. Usage is that you call Invalidate and
+/// Scroll, and implement the Client interface. Your OnPaint handler will
+/// then get called with coalesced paint events.
+///
+/// This class is basically a <code>PaintAggregator</code> that groups updates,
+/// plus management of callbacks for scheduling paints.
+///
+/// <strong>Example:</strong>
+///
+/// @code
+///
+///  class MyClass : public pp::Instance, public PaintManager::Client {
+///   public:
+///    MyClass() {
+///      paint_manager_.Initialize(this, this, false);
+///    }
+///
+///    void ViewChanged(const pp::Rect& position, const pp::Rect& clip) {
+///      paint_manager_.SetSize(position.size());
+///    }
+///
+///    void DoSomething() {
+///      // This function does something like respond to an event that causes
+///      // the screen to need updating.
+///      paint_manager_.InvalidateRect(some_rect);
+///    }
+///
+///    // Implementation of PaintManager::Client
+///    virtual bool OnPaint(pp::Graphics2D& device,
+///                         const pp::PaintUpdate& update) {
+///      // If our app needed scrolling, we would apply that first here.
+///
+///      // Then we would either repaint the area returned by GetPaintBounds or
+///      // iterate through all the paint_rects.
+///
+///      // The caller will call Flush() for us, so don't do that here.
+///      return true;
+///    }
+///
+///   private:
+///    pp::PaintManager paint_manager_;
+///  };
+/// @endcode
 class PaintManager {
  public:
   class Client {
    public:
-    // Paints the given invalid area of the plugin to the given graphics
-    // device. Returns true if anything was painted.
-    //
-    // You are given the list of rects to paint in |paint_rects|, and the
-    // union of all of these rects in |paint_bounds|. You only have to paint
-    // the area inside each of the |paint_rects|, but can paint more if you
-    // want (some apps may just want to paint the union).
-    //
-    // Do not call Flush() on the graphics device, this will be done
-    // automatically if you return true from this function since the
-    // PaintManager needs to handle the callback.
-    //
-    // It is legal for you to cause invalidates inside of Paint which will
-    // then get executed as soon as the Flush for this update has completed.
-    // However, this is not very nice to the host system since it will spin the
-    // CPU, possibly updating much faster than necessary. It is best to have a
-    // 1/60 second timer to do an invalidate instead. This will limit your
-    // animation to the slower of 60Hz or "however fast Flush can complete."
+    /// OnPaint() paints the given invalid area of the instance to the given
+    /// graphics device. Returns true if anything was painted.
+    ///
+    /// You are given the list of rects to paint in <code>paint_rects</code>,
+    /// and the union of all of these rects in <code>paint_bounds</code>. You
+    /// only have to paint the area inside each of the
+    /// <code>paint_rects</code>, but can paint more if you want (some apps may
+    /// just want to paint the union).
+    ///
+    /// Do not call Flush() on the graphics device, this will be done
+    /// automatically if you return true from this function since the
+    /// <code>PaintManager</code> needs to handle the callback.
+    ///
+    /// It is legal for you to cause invalidates inside of Paint which will
+    /// then get executed as soon as the Flush for this update has completed.
+    /// However, this is not very nice to the host system since it will spin the
+    /// CPU, possibly updating much faster than necessary. It is best to have a
+    /// 1/60 second timer to do an invalidate instead. This will limit your
+    /// animation to the slower of 60Hz or "however fast Flush can complete."
+    ///
+    /// @param graphics A <code>Graphics2D</code> to be painted.
+    /// @param paint_rects A list of rects to paint.
+    /// @param paint_bounds A union of the rects to paint.
     virtual bool OnPaint(Graphics2D& graphics,
                          const std::vector<Rect>& paint_rects,
                          const Rect& paint_bounds) = 0;
@@ -90,84 +102,143 @@ class PaintManager {
     virtual ~Client() {}
   };
 
-  // If you use this version of the constructor, you must call Initialize()
-  // below.
+  /// Default constructor for creating an is_null() <code>PaintManager</code>
+  /// object. If you use this version of the constructor, you must call
+  /// Initialize() below.
   PaintManager();
 
-  // The instance is the plugin instance using this paint manager to do its
-  // painting. Painting will automatically go to this instance and you don't
-  // have to manually bind any device context (this is all handled by the
-  // paint manager).
-  //
-  // The Client is a non-owning pointer and must remain valid (normally the
-  // object implementing the Client interface will own the paint manager).
-  //
-  // The is_always_opaque flag will be passed to the device contexts that this
-  // class creates. Set this to true if your plugin always draws an opaque
-  // image to the device. This is used as a hint to the browser that it does
-  // not need to do alpha blending, which speeds up painting. If you generate
-  // non-opqaue pixels or aren't sure, set this to false for more general
-  // blending.
-  //
-  // If you set is_always_opaque, your alpha channel should always be set to
-  // 0xFF or there may be painting artifacts. Being opaque will allow the
-  // browser to do a memcpy rather than a blend to paint the plugin, and this
-  // means your alpha values will get set on the page backing store. If these
-  // values are incorrect, it could mess up future blending. If you aren't
-  // sure, it is always correct to specify that it it not opaque.
-  //
-  // You will need to call SetSize before this class will do anything. Normally
-  // you do this from the ViewChanged method of your plugin instance.
+  /// A constructor to create a new <code>PaintManager</code> with an instance
+  /// and client.
+  ///
+  /// <strong>Note:</strong> You will need to call SetSize() before this class
+  /// will do anything. Normally you do this from the <code>ViewChanged</code>
+  /// method of your instance.
+  ///
+  /// @param instance The instance using this paint manager to do its
+  /// painting. Painting will automatically go to this instance and you don't
+  /// have to manually bind any device context (this is all handled by the
+  /// paint manager).
+  ///
+  /// @param client A non-owning pointer and must remain valid (normally the
+  /// object implementing the Client interface will own the paint manager).
+  ///
+  /// @param is_always_opaque A flag passed to the device contexts that this
+  /// class creates. Set this to true if your instance always draws an opaque
+  /// image to the device. This is used as a hint to the browser that it does
+  /// not need to do alpha blending, which speeds up painting. If you generate
+  /// non-opqaue pixels or aren't sure, set this to false for more general
+  /// blending.
+  ///
+  /// If you set is_always_opaque, your alpha channel should always be set to
+  /// 0xFF or there may be painting artifacts. Being opaque will allow the
+  /// browser to do a memcpy rather than a blend to paint the plugin, and this
+  /// means your alpha values will get set on the page backing store. If these
+  /// values are incorrect, it could mess up future blending. If you aren't
+  /// sure, it is always correct to specify that it it not opaque.
   PaintManager(Instance* instance, Client* client, bool is_always_opaque);
 
+  /// Destructor.
   ~PaintManager();
 
-  // You must call this function before using if you use the 0-arg constructor.
-  // See the constructor for what these arguments mean.
+  /// Initialize() must be called if you are using the 0-arg constructor.
+  ///
+  /// @param instance The instance using this paint manager to do its
+  /// painting. Painting will automatically go to this instance and you don't
+  /// have to manually bind any device context (this is all handled by the
+  /// paint manager).
+  /// @param client A non-owning pointer and must remain valid (normally the
+  /// object implementing the Client interface will own the paint manager).
+  /// @param is_always_opaque A flag passed to the device contexts that this
+  /// class creates. Set this to true if your instance always draws an opaque
+  /// image to the device. This is used as a hint to the browser that it does
+  /// not need to do alpha blending, which speeds up painting. If you generate
+  /// non-opqaue pixels or aren't sure, set this to false for more general
+  /// blending.
+  ///
+  /// If you set is_always_opaque, your alpha channel should always be set to
+  /// 0xFF or there may be painting artifacts. Being opaque will allow the
+  /// browser to do a memcpy rather than a blend to paint the plugin, and this
+  /// means your alpha values will get set on the page backing store. If these
+  /// values are incorrect, it could mess up future blending. If you aren't
+  /// sure, it is always correct to specify that it it not opaque.
   void Initialize(Instance* instance, Client* client, bool is_always_opaque);
 
-  // Setters for the configuration settings in the paint aggregator.
-  // See paint_aggregator.h for what these mean.
+  /// Setter function setting the max ratio of paint rect area to scroll rect
+  /// area that we will tolerate before downgrading the scroll into a repaint.
+  ///
+  /// If the combined area of paint rects contained within the scroll
+  /// rect grows too large, then we might as well just treat
+  /// the scroll rect as a paint rect.
+  ///
+  /// @param[in] area The max ratio of paint rect area to scroll rect area that
+  /// we will tolerate before downgrading the scroll into a repaint.
   void set_max_redundant_paint_to_scroll_area(float area) {
     aggregator_.set_max_redundant_paint_to_scroll_area(area);
   }
+
+  /// Setter function for setting the maximum number of paint rects. If we
+  /// exceed this limit, then we'll start combining paint rects (see
+  /// CombinePaintRects(). This limiting can be important since there is
+  /// typically some overhead in deciding what to paint. If your module is fast
+  /// at doing these computations, raise this threshold, if your module is
+  /// slow, lower it (probably requires some tuning to find the right value).
+  ///
+  /// @param[in] max_rects The maximum number of paint rects.
   void set_max_paint_rects(size_t max_rects) {
     aggregator_.set_max_paint_rects(max_rects);
   }
 
-  // Sets the size of the plugin. If the size is the same as the previous call,
-  // this will be a NOP. If the size has changed, a new device will be
-  // allocated to the given size and a paint to that device will be scheduled.
-  //
-  // This is intended to be called from ViewChanged with the size of the
-  // plugin. Since it tracks the old size and only allocates when the size
-  // changes, you can always call this function without worrying about whether
-  // the size changed or ViewChanged is called for another reason (like the
-  // position changed).
+  /// SetSize() sets the size of the instance. If the size is the same as the
+  /// previous call, this will be a NOP. If the size has changed, a new device
+  /// will be allocated to the given size and a paint to that device will be
+  /// scheduled.
+  ///
+  /// This function is intended to be called from <code>ViewChanged</code> with
+  /// the size of the instance. Since it tracks the old size and only allocates
+  /// when the size changes, you can always call this function without worrying
+  /// about whether the size changed or ViewChanged() is called for another
+  /// reason (like the position changed).
+  ///
+  /// @param new_size The new size for the instance.
   void SetSize(const Size& new_size);
 
-  // Provides access to the underlying device in case you need it. If you have
-  // done a SetSize, note that the graphics context won't be updated until
-  // right before the next OnPaint call.
-  //
-  // Note: if you call Flush on this device the paint manager will get very
-  // confused, don't do this!
+  /// This function provides access to the underlying device in case you need
+  /// it. If you have done a SetSize(), note that the graphics context won't be
+  /// updated until right before the next call to OnPaint().
+  ///
+  /// <strong>Note:</strong> If you call Flush on this device the paint manager
+  /// will get very confused, don't do this!
   const Graphics2D& graphics() const { return graphics_; }
+
+  /// This function provides access to the underlying device in case you need
+  /// it. If you have done a SetSize(), note that the graphics context won't be
+  /// updated until right before the next call to OnPaint().
+  ///
+  /// <strong>Note:</strong> If you call Flush on this device the paint manager
+  /// will get very confused, don't do this!
   Graphics2D& graphics() { return graphics_; }
 
-  // Invalidate the entire plugin.
+  /// Invalidate() invalidate the entire instance.
   void Invalidate();
 
-  // Invalidate the given rect.
+  /// InvalidateRect() Invalidate the provided rect.
+  ///
+  /// @param rect The <code>Rect</code> to be invalidated.
   void InvalidateRect(const Rect& rect);
 
-  // The given rect should be scrolled by the given amounts.
+  /// ScrollRect() scrolls the provided <code>clip_rect</code> by the
+  /// <code>amount</code> argument.
+  ///
+  /// @param clip_rect The clip rectangle to scroll.
+  /// @param amount The amount to scroll <code>clip_rect</code>.
   void ScrollRect(const Rect& clip_rect, const Point& amount);
 
-  // Returns the size of the graphics context for the next paint operation.
-  // This is the pending size if a resize is pending (the plugin has called
-  // SetSize but we haven't actually painted it yet), or the current size of
-  // no resize is pending.
+  /// GetEffectiveSize() returns the size of the graphics context for the
+  /// next paint operation. This is the pending size if a resize is pending
+  /// (the instance has called SetSize() but we haven't actually painted it
+  /// yet), or the current size of no resize is pending.
+  ///
+  /// @return The effetive size.
   Size GetEffectiveSize() const;
 
  private: