devtools: document classes and method, remove unneeded methods

This documents DevTools classes and methods. In addition it also
removes some methods that aren't needed anymore.

Change-Id: I550e2ce197d1565b4f770eb7dd59b2195f2230a3
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/112379
Tested-by: Jenkins
Reviewed-by: Tomaž Vajngerl <quikee@gmail.com>

4 files changed, 43 insertions, 2 deletions

diff --git a/include/sfx2/devtools/DevelopmentToolChildWindow.hxx b/include/sfx2/devtools/DevelopmentToolChildWindow.hxx
index adf5adf44980..d78ac5c2e2ce 100644
--- a/include/sfx2/devtools/DevelopmentToolChildWindow.hxx
+++ b/include/sfx2/devtools/DevelopmentToolChildWindow.hxx
@@ -13,6 +13,9 @@
 #include <sfx2/dllapi.h>
 #include <sfx2/childwin.hxx>
 
+/**
+ * Necessary child window for the development tools docking window
+ */
 class SAL_WARN_UNUSED SFX2_DLLPUBLIC DevelopmentToolChildWindow final : public SfxChildWindow
 {
     SFX_DECL_CHILDWINDOW_WITHID(DevelopmentToolChildWindow);
diff --git a/include/sfx2/devtools/DevelopmentToolDockingWindow.hxx b/include/sfx2/devtools/DevelopmentToolDockingWindow.hxx
index f5c214949c6a..1d05948cd51f 100644
--- a/include/sfx2/devtools/DevelopmentToolDockingWindow.hxx
+++ b/include/sfx2/devtools/DevelopmentToolDockingWindow.hxx
@@ -26,6 +26,11 @@
 
 #include <unordered_map>
 
+/** Development tool main docking window
+ *
+ * Contains two sides. Left side contains the simplified DOM tree and
+ * the right side the object inspector tree.
+ */
 class SFX2_DLLPUBLIC DevelopmentToolDockingWindow final : public SfxDockingWindow
 {
 private:
@@ -39,20 +44,22 @@ private:
     std::unique_ptr<weld::Toolbar> mpObjectInspectorToolbar;
     std::unique_ptr<weld::Notebook> mpObjectInspectorNotebook;
 
+    // Reference to the root object for the current document
     css::uno::Reference<css::uno::XInterface> mxRoot;
+    // Stores the current selected object in the document
     css::uno::Reference<css::uno::XInterface> mxCurrentSelection;
     css::uno::Reference<css::view::XSelectionChangeListener> mxSelectionListener;
     css::uno::Reference<css::view::XSelectionSupplier> mxSelectionSupplier;
 
+    // Handler for the DOM tree
     DocumentModelTreeHandler maDocumentModelTreeHandler;
+    // Handler for the object inspector tree
     ObjectInspectorTreeHandler maObjectInspectorTreeHandler;
 
     DECL_LINK(DocumentModelTreeViewSelectionHandler, weld::TreeView&, void);
     DECL_LINK(SelectionToggled, weld::ToggleButton&, void);
 
-    void inspectDocument();
     void updateSelection();
-    void inspectSelectionOrRoot();
 
 public:
     DevelopmentToolDockingWindow(SfxBindings* pBindings, SfxChildWindow* pChildWindow,
@@ -64,10 +71,13 @@ public:
 
     virtual void ToggleFloatingMode() override;
 
+    // Inspect the input object in the object inspector
     void introspect(css::uno::Reference<css::uno::XInterface> const& xInterface);
 
+    // Signals that the selected object in the document changes
     void selectionChanged(css::uno::Reference<css::uno::XInterface> const& xInterface);
 
+    // Signals to change to the current selected object in the object inspector
     void changeToCurrentSelection();
 };
 
diff --git a/include/sfx2/devtools/DocumentModelTreeHandler.hxx b/include/sfx2/devtools/DocumentModelTreeHandler.hxx
index 03f5ed274aa4..17b853b36c6f 100644
--- a/include/sfx2/devtools/DocumentModelTreeHandler.hxx
+++ b/include/sfx2/devtools/DocumentModelTreeHandler.hxx
@@ -18,12 +18,19 @@
 
 #include <unordered_map>
 
+/** Document model tree handler
+ *
+ * Handles the DOM tree part of DevTools, which includes interaction with
+ * the DOM tree view UI elements and the DOM model.
+ */
 class DocumentModelTreeHandler
 {
 private:
     std::unique_ptr<weld::TreeView>& mpDocumentModelTree;
     css::uno::Reference<css::uno::XInterface> mxDocument;
 
+    // Clears all children of a tree node, where the parent is
+    // identified by the input tree iter.
     void clearChildren(weld::TreeIter const& rParent);
 
 public:
@@ -37,6 +44,8 @@ public:
     static css::uno::Reference<css::uno::XInterface> getObjectByID(OUString const& rID);
 
     void dispose();
+
+    // selects the input object if it exists in the DOM tree view
     void selectObject(css::uno::Reference<css::uno::XInterface> const& xInterface);
 };
 
diff --git a/include/sfx2/devtools/ObjectInspectorTreeHandler.hxx b/include/sfx2/devtools/ObjectInspectorTreeHandler.hxx
index 58b4c833961c..1d7000371eba 100644
--- a/include/sfx2/devtools/ObjectInspectorTreeHandler.hxx
+++ b/include/sfx2/devtools/ObjectInspectorTreeHandler.hxx
@@ -22,6 +22,12 @@
 #include <memory>
 #include <deque>
 
+/** Object inspector tree handler
+ *
+ * Handles the object inspector part of DevTools - mainly interaction
+ * between UI objects that consist of the object inspector.
+ *
+ */
 class ObjectInspectorTreeHandler
 {
 private:
@@ -33,8 +39,11 @@ private:
     std::unique_ptr<weld::Toolbar>& mpObjectInspectorToolbar;
     std::unique_ptr<weld::Notebook>& mpObjectInspectorNotebook;
 
+    // object stack to remember previously inspected objects so it is
+    // possible to return back to them
     std::deque<css::uno::Any> maInspectionStack;
 
+    // just the current context
     css::uno::Reference<css::uno::XComponentContext> mxContext;
 
     static void clearObjectInspectorChildren(std::unique_ptr<weld::TreeView>& pTreeView,
@@ -50,6 +59,7 @@ private:
 
     void inspectObject(css::uno::Reference<css::uno::XInterface> const& xInterface);
 
+    // Object stack handling
     void clearStack();
     void addToStack(css::uno::Any const& rAny);
     css::uno::Any popFromStack();
@@ -65,14 +75,23 @@ public:
                                std::unique_ptr<weld::Toolbar>& pObjectInspectorToolbar,
                                std::unique_ptr<weld::Notebook>& pObjectInspectorNotebook);
 
+    // callbacks when a node in the tree view is expanded
     DECL_LINK(ExpandingHandlerInterfaces, const weld::TreeIter&, bool);
     DECL_LINK(ExpandingHandlerServices, const weld::TreeIter&, bool);
     DECL_LINK(ExpandingHandlerProperties, const weld::TreeIter&, bool);
     DECL_LINK(ExpandingHandlerMethods, const weld::TreeIter&, bool);
+
+    // callback when the tree view selection changed to a different node
     DECL_LINK(SelectionChanged, weld::TreeView&, void);
 
+    // callback when a pop-up is triggered on a tree view node
     DECL_LINK(PopupMenuHandler, const CommandEvent&, bool);
+
+    // callback when a button is clicked on a toolbar
     DECL_LINK(ToolbarButtonClicked, const OString&, void);
+
+    // callback when a page is entered or left on the notebook bar for
+    // different categories
     DECL_LINK(NotebookEnterPage, const OString&, void);
     DECL_LINK(NotebookLeavePage, const OString&, bool);