API doc improvements

src/wayland/clientconnection.h

@@ -35,13 +35,35 @@ namespace Server
 
 class Display;
 
+/**
+ * @brief Convenient Class which represents a wl_client.
+ *
+ * The ClientConnection gets automatically created for a wl_client when a wl_client is
+ * first used in the context of KWayland::Server. In particular the signal
+ * @link Display::clientConnected @endlink will be emitted.
+ *
+ * @see Display
+ **/
 class KWAYLANDSERVER_EXPORT ClientConnection : public QObject
 {
     Q_OBJECT
 public:
     virtual ~ClientConnection();
 
+    /**
+     * Flushes the connection to this client. Ensures that all events are pushed to the client.
+     **/
     void flush();
+    /**
+     * Creates a new wl_resource for the provided @p interface.
+     *
+     * Thus a convenient wrapper around wl_resource_create
+     *
+     * @param interface
+     * @param version
+     * @param id
+     * @returns the created native wl_resource
+     **/
     wl_resource *createResource(const wl_interface *interface, quint32 version, quint32 id);
     /**
      * Get the wl_resource associated with the given @p id.
@@ -49,17 +71,56 @@ public:
      **/
     wl_resource *getResource(quint32 id);
 
+    /**
+     * @returns the native wl_client this ClientConnection represents.
+     **/
     wl_client *client();
+    /**
+     * @returns The Display this ClientConnection is connected to
+     **/
     Display *display();
 
+    /**
+     * The pid of the ClientConnection endpoint.
+     *
+     * Please note: if the ClientConnection got created with @link Display::createClient @endlink
+     * the pid will be identical to the process running the KWayland::Server::Display.
+     *
+     * @returns The pid of the connection.
+     **/
     pid_t processId() const;
+    /**
+     * The uid of the ClientConnection endpoint.
+     *
+     * Please note: if the ClientConnection got created with @link Display::createClient @endlink
+     * the uid will be identical to the process running the KWayland::Server::Display.
+     *
+     * @returns The uid of the connection.
+     **/
     uid_t userId() const;
+    /**
+     * The gid of the ClientConnection endpoint.
+     *
+     * Please note: if the ClientConnection got created with @link Display::createClient @endlink
+     * the gid will be identical to the process running the KWayland::Server::Display.
+     *
+     * @returns The gid of the connection.
+     **/
     gid_t groupId() const;
 
+    /**
+     * Cast operator the native wl_client this ClientConnection represents.
+     **/
     operator wl_client*();
+    /**
+     * Cast operator the native wl_client this ClientConnection represents.
+     **/
     operator wl_client*() const;
 
 Q_SIGNALS:
+    /**
+     * Signal emitted when the ClientConnection got disconnected from the server.
+     **/
     void disconnected(KWayland::Server::ClientConnection*);
 
 private:

src/wayland/display.h

@@ -51,6 +51,11 @@ class ContrastManagerInterface;
 class ShellInterface;
 class SubCompositorInterface;
 
+/**
+ * @brief Class holding the Wayland server display loop.
+ *
+ * @todo Improve documentation
+ **/
 class KWAYLANDSERVER_EXPORT Display : public QObject
 {
     Q_OBJECT

src/wayland/keyboard_interface.h

@@ -32,12 +32,19 @@ namespace Server
 class SeatInterface;
 class SurfaceInterface;
 
+/**
+ * @brief Resource for the wl_keyboard interface.
+ *
+ **/
 class KWAYLANDSERVER_EXPORT KeyboardInterface : public Resource
 {
     Q_OBJECT
 public:
     virtual ~KeyboardInterface();
 
+    /**
+     * @returns the focused SurfaceInterface on this keyboard resource, if any.
+     **/
     SurfaceInterface *focusedSurface() const;
 
 private:

src/wayland/pointer_interface.h

@@ -33,11 +33,19 @@ class Cursor;
 class SeatInterface;
 class SurfaceInterface;
 
+/**
+ * @brief Resource for the wl_pointer interface.
+ *
+ **/
 class KWAYLANDSERVER_EXPORT PointerInterface : public Resource
 {
     Q_OBJECT
 public:
     virtual ~PointerInterface();
+
+    /**
+     * @returns the focused SurfaceInterface on this pointer resource, if any.
+     **/
     SurfaceInterface *focusedSurface() const;
 
     /**

src/wayland/server/buffer_interface.h

@@ -35,17 +35,78 @@ namespace Server
 class SurfaceInterface;
 
 
+/**
+ * @brief Reference counted representation of a Wayland buffer on Server side.
+ *
+ * This class encapsulates a rendering buffer which is normally attached to a SurfaceInterface.
+ * A client should not render to a Wayland buffer as long as the buffer gets used by the server.
+ * The server signals whether it's still used. This class provides a convenience access for this
+ * functionality by performing reference counting and deleting the BufferInterface instance
+ * automatically once it is no longer accessed.
+ *
+ * The BufferInterface is referenced as long as it is attached to a SurfaceInterface. If one wants
+ * to keep access to the BufferInterface for a longer time ensure to call ref on first usage and
+ * unref again once access to it is no longer needed.
+ *
+ * In Wayland the buffer is an abstract concept and a buffer might represent multiple different
+ * concrete buffer techniques. This class has direct support for shared memory buffers built and
+ * provides access to the native buffer for different (e.g. EGL/drm) buffers.
+ *
+ * If the EGL display has been registered in the Display the BufferInterface can also provide
+ * some information about an EGL/drm buffer.
+ *
+ * For shared memory buffers a direct conversion to a memory-mapped QImage possible using the
+ * data method. Please refer to the documentation for notes on the restrictions when using the
+ * shared memory-mapped QImages.
+ *
+ * @see Display
+ * @see SurfaceInterace
+ **/
 class KWAYLANDSERVER_EXPORT BufferInterface : public QObject
 {
     Q_OBJECT
 public:
     virtual ~BufferInterface();
+    /**
+     * Reference the BufferInterface.
+     *
+     * As long as the reference counting has not reached @c 0 the BufferInterface is valid
+     * and blocked for usage by the client.
+     *
+     * @see unref
+     * @see isReferenced
+     **/
     void ref();
+    /**
+     * Unreference the BufferInterface.
+     *
+     * If the reference counting reached @c 0 the BufferInterface is released, so that the
+     * client can use it again. The instance of this BufferInterface will be automatically
+     * deleted.
+     *
+     * @see ref
+     * @see isReferenced
+     **/
     void unref();
+    /**
+     * @returns whether the BufferInterface is currently referenced
+     *
+     * @see ref
+     * @see unref
+     **/
     bool isReferenced() const;
 
+    /**
+     * @returns The SurfaceInterface this BufferInterface is attached to.
+     **/
     SurfaceInterface *surface() const;
+    /**
+     * @returns The native wl_shm_buffer if the BufferInterface represents a shared memory buffer, otherwise @c nullptr.
+     **/
     wl_shm_buffer *shmBuffer();
+    /**
+     * @returns the native wl_resource wrapped by this BufferInterface.
+     **/
     wl_resource *resource() const;
 
     /**

src/wayland/server/global.h

@@ -32,18 +32,62 @@ namespace Server
 {
 class Display;
 
+/**
+ * @brief Base class for all Globals.
+ *
+ * Any class representing a Global should be derived from this base class.
+ * This class provides common functionality for all globals. A global is an
+ * object listed as an interface on the registry on client side.
+ *
+ * Normally a Global gets factored by the Display. For each Global-derived class there
+ * is a dedicated factory method. After creating an instance through the factory method
+ * it is not yet announced on the registry. One needs to call ::create on it. This allows
+ * to setup the Global before it gets announced, ensuring that the client's state is correct
+ * from the start.
+ *
+ * As an example shown for @link OutputInterface @endlink:
+ * @code
+ * Display *display; // The existing display
+ * auto o = display->createOutput();
+ * o->setManufacturer(QStringLiteral("The KDE Community"));
+ * // setup further data on the OutputInterface
+ * o->create(); // announces OutputInterface
+ * @endcode
+ *
+ * @see Display
+ *
+ **/
 class KWAYLANDSERVER_EXPORT Global : public QObject
 {
     Q_OBJECT
 public:
     virtual ~Global();
+    /**
+     * Creates the global by creating a native wl_global and by that announcing it
+     * to the clients.
+     **/
     void create();
+    /**
+     * Destroys the low level wl_global. Afterwards the Global is no longer shown to clients.
+     **/
     void destroy();
+    /**
+     * @returns whether the Global got created
+     **/
     bool isValid() const;
 
+    /**
+     * @returns the Display the Global got created on.
+     */
     Display *display();
 
+    /**
+     * Cast operator to the native wl_global this Global represents.
+     **/
     operator wl_global*();
+    /**
+     * Cast operator to the native wl_global this Global represents.
+     **/
     operator wl_global*() const;
 
 protected:

src/wayland/server/resource.h

@@ -35,6 +35,14 @@ namespace Server
 class ClientConnection;
 class Global;
 
+/**
+ * @brief Represents a bound Resource.
+ *
+ * A Resource normally gets created by a @link Global @endlink.
+ *
+ * The Resource is a base class for all specific resources and provides
+ * access to various common aspects.
+ **/
 class KWAYLANDSERVER_EXPORT Resource : public QObject
 {
     Q_OBJECT
@@ -42,9 +50,21 @@ public:
     virtual ~Resource();
     void create(ClientConnection *client, quint32 version, quint32 id);
 
+    /**
+     * @returns the native wl_resource this Resource was created for.
+     **/
     wl_resource *resource();
+    /**
+     * @returns The ClientConnection for which the Resource was created.
+     **/
     ClientConnection *client();
+    /**
+     * @returns The Global which created the Resource.
+     **/
     Global *global();
+    /**
+     * @returns the native parent wl_resource, e.g. the wl_resource bound on the Global
+     **/
     wl_resource *parentResource() const;
     /**
      * @returns The id of this Resource if it is created, otherwise @c 0.

src/wayland/touch_interface.h

@@ -31,6 +31,10 @@ namespace Server
 
 class SeatInterface;
 
+/**
+ * @brief Resource for the wl_touch interface.
+ *
+ **/
 class KWAYLANDSERVER_EXPORT TouchInterface : public Resource
 {
     Q_OBJECT