Super duper mega (fun!) commit: replaced encoding=utf-8 with fileencoding=utf-8 in...

[inkscape.git] / src / xml / subtree.h

diff --git a/src/xml/subtree.h b/src/xml/subtree.h
index 9e2512e83786a294cb2e47171d0fcc171047bbfd..deee0cab1639a713c6c04a27edfc94eaf96df243 100644 (file)
--- a/src/xml/subtree.h
+++ b/src/xml/subtree.h
@@ -1,7 +1,7 @@
-/*
- * XML::Subtree - proxy for an XML subtree
- *
- * Copyright 2005 MenTaLguY <mental@rydia.net>
+/** @file
+ * @brief Object representing a subtree of the XML document
+ */
+/* Copyright 2005 MenTaLguY <mental@rydia.net>
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -15,22 +15,45 @@
 #ifndef SEEN_INKSCAPE_XML_SUBTREE_H
 #define SEEN_INKSCAPE_XML_SUBTREE_H
 
-#include "xml/node-observer.h"
+#include "gc-managed.h"
+#include "xml/xml-forward.h"
 #include "xml/composite-node-observer.h"
-#include "gc-finalized.h"
 
 namespace Inkscape {
 namespace XML {
 
-class Node;
-
+/**
+ * @brief Represents a node and all its descendants
+ *
+ * This is a convenience object for node operations that affect all of the node's descendants.
+ * Currently the only such operations are adding and removing subtree observers
+ * and synthesizing events for the entire subtree.
+ */
 class Subtree : public GC::Managed<GC::SCANNED, GC::MANUAL> {
 public:
     Subtree(Node &root);
     ~Subtree();
 
+    /**
+     * @brief Synthesize events for the entire subtree
+     *
+     * This method notifies the specified observer of node changes equivalent to creating
+     * this subtree from scratch. The notifications recurse into the tree depth-first.
+     * Currently this is the only method that provides extra functionality compared to
+     * the public methods of Node.
+     */
     void synthesizeEvents(NodeObserver &observer);
+    /**
+     * @brief Add an observer watching for subtree changes
+     *
+     * Equivalent to Node::addSubtreeObserver().
+     */
     void addObserver(NodeObserver &observer);
+    /**
+     * @brief Add an observer watching for subtree changes
+     *
+     * Equivalent to Node::removeSubtreeObserver().
+     */
     void removeObserver(NodeObserver &observer);
 
 private:
@@ -51,4 +74,4 @@ private:
   fill-column:99
   End:
 */
-// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :
+// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 :