First pass at Comment API

include/core/SkCanvas.h

 
 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 
 #ifndef SkCanvas_DEFINED
@@ skipping 829 matching lines @@
                               const SkPaint& paint);
 
     /** Send a blob of data to the canvas.
         For canvases that draw, this call is effectively a no-op, as the data
         is not parsed, but just ignored. However, this call exists for
         subclasses like SkPicture's recording canvas, that can store the data
         and then play it back later (via another call to drawData).
      */
     virtual void drawData(const void* data, size_t length);
 
+    /** Add comments. beginGroup/endGroup open/close a new group. Each
+        comment added via addComment is notionally attached to its enclosing 
+        group. Top-level comments simply belong to no group.
+     */
+    virtual void beginGroup(const char* description);
+    virtual void addComment(const char* kywd, const char* value);
+    virtual void endGroup();

[djsollen, 2013/04/24 13:01:55]

Perhaps beginCommentGroup and endCommentGroup would be more descriptive.

+
     //////////////////////////////////////////////////////////////////////////
 
     /** Get the current bounder object.
         The bounder's reference count is unchaged.
         @return the canva's bounder (or NULL).
     */
     SkBounder*  getBounder() const { return fBounder; }
 
     /** Set a new bounder (or NULL).
         Pass NULL to clear any previous bounder.
@@ skipping 262 matching lines @@
             fCanvas->restoreToCount(fSaveCount);
             fCanvas = NULL;
         }
     }
 
 private:
     SkCanvas*   fCanvas;
     int         fSaveCount;
 };
 
+/** Stack helper class to automatically open and close a comment block
+ */
+class SkAutoCommentBlock : SkNoncopyable {
+public:
+    SkAutoCommentBlock(SkCanvas* canvas, const char* description) {
+        this->init(canvas, description);
+    }
+
+    ~SkAutoCommentBlock() {
+        if (NULL != fCanvas) {
+            fCanvas->endGroup();
+        }
+    }
+
+private:
+    SkCanvas* fCanvas;
+
+    void init(SkCanvas* canvas, const char* description) {
+        fCanvas = canvas;
+        if (NULL != fCanvas) {
+            fCanvas->beginGroup(description);
+        }
+    }
+};
+
 #endif