New C++ Docs.

ppapi/cpp/paint_manager.h

Index: ppapi/cpp/paint_manager.h
===================================================================
--- ppapi/cpp/paint_manager.h	(revision 95101)
+++ ppapi/cpp/paint_manager.h	(working copy)
@@ -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 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

[dmichael (off chromium), 2011/08/03 15:50:49]

Why are you using @code here instead of <code> like everywhere else?

[jond, 2011/08/03 20:15:08]

We're using @code and @endcode for large code blocks. No real reason other than
a few things used it and I stayed with it.

On 2011/08/03 15:50:49, dmichael wrote:

[dmichael (off chromium), 2011/08/04 16:33:38]

Is the @code tag very widespread? There doesn't seem to be a reason to use a
different tag; I find <code> more readable anyway. Can we just use <code> and
</code> so we're more consistent?

+///
+///  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

[dmichael (off chromium), 2011/08/03 15:50:49]

Do we wrap function names with <code> tags? If so, you should do OnPaint() here
and Flush() below.
Do we have a place where we list our documentation conventions? Maybe we
should...

[jond, 2011/08/03 20:15:08]

<code></code> is only used for things that exist in code exactly as they are in
the docs. You never see Flush() in code, for example, so its not surrounded by
code tags. I need to update the conventions a bit, but we have them. 2011/08/03
15:50:49, dmichael wrote:

+    /// 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,140 @@
     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() is called before using if you use the 0-arg constructor.

[dmichael (off chromium), 2011/08/03 15:50:49]

Reword as a 'You must' kind of thing; the developer must call this if they use
the 0-arg constructor.

[jond, 2011/08/03 20:15:08]

Done.

[jond, 2011/08/03 20:15:08]

Done.

+  ///
+  /// @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 intended to be called from <code>ViewChanged</code> with

[dmichael (off chromium), 2011/08/03 15:50:49]

you lost the 'is' before intentended

+  /// 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>Rect</code> by the provided

[dmichael (off chromium), 2011/08/03 15:50:49]

'by the provided' -> 'by the given'?
It might read better to not use 'provided' twice.

[jond, 2011/08/03 20:15:08]

Done.

[jond, 2011/08/03 20:15:08]

Done.

+  /// amount.
+  ///
+  /// @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: