[server] Another round of docu improvements

src/wayland/compositor_interface.h

@@ -36,6 +36,10 @@ namespace Server
 class Display;
 class SurfaceInterface;
 
+/**
+ * @brief Represents the Global for wl_compositor interface.
+ *
+ **/
 class KWAYLANDSERVER_EXPORT CompositorInterface : public Global
 {
     Q_OBJECT
@@ -43,7 +47,13 @@ public:
     virtual ~CompositorInterface();
 
 Q_SIGNALS:
+    /**
+     * Emitted whenever this CompositorInterface created a SurfaceInterface.
+     **/
     void surfaceCreated(KWayland::Server::SurfaceInterface*);
+    /**
+     * Emitted whenever this CompositorInterface created a RegionInterface.
+     **/
     void regionCreated(KWayland::Server::RegionInterface*);
 
 private:

src/wayland/pointer_interface.h

@@ -36,6 +36,7 @@ class SurfaceInterface;
 /**
  * @brief Resource for the wl_pointer interface.
  *
+ * @see SeatInterface
  **/
 class KWAYLANDSERVER_EXPORT PointerInterface : public Resource
 {

src/wayland/seat_interface.h

@@ -38,17 +38,83 @@ namespace Server
 {
 
 class Display;
-class KeyboardInterface;
 class SurfaceInterface;
 
+/**
+ * @brief Represents a Seat on the Wayland Display.
+ *
+ * A Seat is a set of input devices (e.g. Keyboard, Pointer and Touch) the client can connect
+ * to. The server needs to announce which input devices are supported and passes dedicated input
+ * focus to a SurfaceInterface. Only the focused surface receives input events.
+ *
+ * The SeatInterface internally handles enter and release events when setting a focused surface.
+ * Also it handles input translation from global to the local coordination, removing the need from
+ * the user of the API to track the focused surfaces and can just interact with this class.
+ *
+ * To create a SeatInterface use @link Display::createSeat @endlink. Then one can set up what is
+ * supported. Last but not least create needs to be called.
+ *
+ * @code
+ * SeatInterface *seat = display->createSeat();
+ * // set up
+ * seat->setName(QStringLiteral("seat0"));
+ * seat->setHasPointer(true);
+ * seat->setHasKeyboard(true);
+ * seat->setHasTouch(false);
+ * // now fully create
+ * seat->create();
+ * @endcode
+ *
+ * To forward input events one needs to set the focused surface, update time stamp and then
+ * forward the actual events:
+ *
+ * @code
+ * // example for pointer
+ * seat->setFocusedPointerSurface(surface, QPointF(100, 200)); // surface at it's global position
+ * seat->setTimestamp(100);
+ * seat->setPointerPos(QPointF(350, 210)); // global pos, local pos in surface: 250,10
+ * seat->setTimestamp(110);
+ * seat->pointerButtonPressed(Qt::LeftButton);
+ * seat->setTimestamp(120);
+ * seat->pointerButtonReleased(Qt::LeftButton);
+ * @endcode
+ *
+ * @see KeyboardInterface
+ * @see PointerInterface
+ * @see TouchInterface
+ * @see SurfaceInterface
+ **/
 class KWAYLANDSERVER_EXPORT SeatInterface : public Global
 {
     Q_OBJECT
+    /**
+     * The name of the Seat
+     **/
     Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
+    /**
+     * Whether the SeatInterface supports a pointer device.
+     **/
     Q_PROPERTY(bool pointer READ hasPointer WRITE setHasPointer NOTIFY hasPointerChanged)
+    /**
+     * Whether the SeatInterface supports a keyboard device.
+     **/
     Q_PROPERTY(bool keyboard READ hasKeyboard WRITE setHasKeyboard NOTIFY hasKeyboardChanged)
+    /**
+     * Whether the SeatInterface supports a touch device.
+     * @deprecated use touch
+     **/
     Q_PROPERTY(bool tourch READ hasTouch WRITE setHasTouch NOTIFY hasTouchChanged)
+    /**
+     * Whether the SeatInterface supports a touch device.
+     **/
+    Q_PROPERTY(bool touch READ hasTouch WRITE setHasTouch NOTIFY hasTouchChanged)
+    /**
+     * The global pointer position.
+     **/
     Q_PROPERTY(QPointF pointerPos READ pointerPos WRITE setPointerPos NOTIFY pointerPosChanged)
+    /**
+     * The current timestamp passed to the input events.
+     **/
     Q_PROPERTY(quint32 timestamp READ timestamp WRITE setTimestamp NOTIFY timestampChanged)
 public:
     virtual ~SeatInterface();
@@ -66,25 +132,113 @@ public:
     void setTimestamp(quint32 time);
     quint32 timestamp() const;
 
-    // pointer related methods
+    /**
+     * @name Pointer related methods
+     **/
+    ///@{
+    /**
+     * Updates the global pointer @p pos.
+     *
+     * Sends a pointer motion event to the focused pointer surface.
+     **/
     void setPointerPos(const QPointF &pos);
+    /**
+     * @returns the global pointer position
+     **/
     QPointF pointerPos() const;
+    /**
+     * Sets the focused pointer @p surface.
+     * All pointer events will be sent to the @p surface till a new focused pointer surface gets
+     * installed. When the focus pointer surface changes a leave event is sent to the previous
+     * focused surface.
+     *
+     * To unset the focused pointer surface pass @c nullptr as @p surface.
+     *
+     * Pointer motion events are adjusted to the local position based on the @p surfacePosition.
+     * If the surface changes it's position in the global coordinate system
+     * use setFocusedPointerSurfacePosition to update.
+     *
+     * @param surface The surface which should become the new focused pointer surface.
+     * @param surfacePosition The position of the surface in the global coordinate system
+     *
+     * @see setPointerPos
+     * @see focucedPointerSurface
+     * @see focusedPointer
+     * @see setFocusedPointerSurfacePosition
+     * @see focusedPointerSurfacePosition
+     **/
     void setFocusedPointerSurface(SurfaceInterface *surface, const QPointF &surfacePosition = QPoint());
+    /**
+     * @returns The currently focused pointer surface, that is the surface receiving pointer events.
+     * @see setFocusedPointerSurface
+     **/
     SurfaceInterface *focusedPointerSurface() const;
+    /**
+     * @returns The PointerInterface belonging to the focused pointer surface, if any.
+     * @see setFocusedPointerSurface
+     **/
     PointerInterface *focusedPointer() const;
+    /**
+     * Updates the global position of the currently focused pointer surface
+     *
+     * @param surfacePosition The new global position of the focused pointer surface
+     * @see focusedPointerSurface
+     * @see setFocusedPointerSurface
+     **/
     void setFocusedPointerSurfacePosition(const QPointF &surfacePosition);
+    /**
+     * @returns The position of the focused pointer surface in global coordinates.
+     * @see setFocusedPointerSurfacePosition
+     * @see setFocusedPointerSurface
+     **/
     QPointF focusedPointerSurfacePosition() const;
+    /**
+     * Marks the @p button as pressed.
+     *
+     * If there is a focused pointer surface a button pressed event is sent to it.
+     *
+     * @param button The Linux button code
+     **/
     void pointerButtonPressed(quint32 button);
+    /**
+     * @overload
+     **/
     void pointerButtonPressed(Qt::MouseButton button);
+    /**
+     * Marks the @p button as released.
+     *
+     * If there is a focused pointer surface a button release event is sent to it.
+     *
+     * @param button The Linux button code
+     **/
     void pointerButtonReleased(quint32 button);
+    /**
+     * @overload
+     **/
     void pointerButtonReleased(Qt::MouseButton button);
+    /**
+     * @returns whether the @p button is pressed
+     **/
     bool isPointerButtonPressed(quint32 button) const;
+    /**
+     * @returns whether the @p button is pressed
+     **/
     bool isPointerButtonPressed(Qt::MouseButton button) const;
+    /**
+     * @returns the last serial for @p button.
+     **/
     quint32 pointerButtonSerial(quint32 button) const;
+    /**
+     * @returns the last serial for @p button.
+     **/
     quint32 pointerButtonSerial(Qt::MouseButton button) const;
     void pointerAxis(Qt::Orientation orientation, quint32 delta);
+    ///@}
 
-    // keyboard related methods
+    /**
+     * @name keyboard related methods
+     **/
+    ///@{
     void setKeymap(int fd, quint32 size);
     void keyPressed(quint32 key);
     void keyReleased(quint32 key);
@@ -129,8 +283,12 @@ public:
     void setFocusedKeyboardSurface(SurfaceInterface *surface);
     SurfaceInterface *focusedKeyboardSurface() const;
     KeyboardInterface *focusedKeyboard() const;
+    ///@}
 
-    // touch related methods
+    /**
+     * @name  touch related methods
+     **/
+    ///@{
     void setFocusedTouchSurface(SurfaceInterface *surface, const QPointF &surfacePosition = QPointF());
     SurfaceInterface *focusedTouchSurface() const;
     TouchInterface *focusedTouch() const;
@@ -142,6 +300,7 @@ public:
     void touchFrame();
     void cancelTouchSequence();
     bool isTouchSequence() const;
+    ///@}
 
     static SeatInterface *get(wl_resource *native);