more clarifications

Author: ammen99

src/api/wayfire/toplevel-view.hpp

@@ -69,8 +69,8 @@ class toplevel_view_interface_t : public virtual wf::view_interface_t
      *
      * Note: xdg-popups / Xwayland menus associated with a view can be found by iterating through all
      * available views, fetching the associated wlroots surfaces (@get_wlr_surface()) and then checking for
-     * potential relations between any pair of views by looking at the specific wlr_xdg_surface / wlr_xwayland
-     * surface interfaces, which provide information about parent xdg surfaces or transient_for relations.
+     * potential relations between any pair of views by looking at shell-specific information, for example
+     * wlr_xdg_popup::parent / wlr_xwayland_surface::parent.
      */
     std::vector<wayfire_toplevel_view> children;
 

src/api/wayfire/unstable/wlr-surface-controller.hpp

@@ -15,6 +15,13 @@ struct node_recheck_constraints_signal
 class wlr_surface_controller_t
 {
   public:
+    /**
+     * Create a new controller for the surface. It will automatically add, remove and update subsurfaces of
+     * the given surface.
+     *
+     * Each subsurface's node will be added as a child of @root_node, and is positioned relative to the
+     * parent surface.
+     */
     static void create_controller(wlr_surface *surface, scene::floating_inner_ptr root_node);
     static void try_free_controller(wlr_surface *surface);
 

src/api/wayfire/view.hpp

@@ -91,7 +91,9 @@ class view_interface_t : public wf::signal::provider_t, public wf::object_base_t
      * by plugins such as wrot, animate, etc.
      *
      * Note: the coordinate system expected by the root node is relative to the output the view is currently
-     * associated with, otherwise undefined.
+     * associated with, otherwise undefined. The coordinate system for children of the surface root node can
+     * be different for each view type, but Wayfire's built-in view types make each subsurface node relative
+     * to its parent surface (see wlr-surface-node.hpp / wlr-surface-controller.hpp for more details).
      */
     const scene::floating_inner_ptr& get_surface_root_node() const;