From 8dddf4fff07fee0d5765143bab3c6f3ded2f0ac5 Mon Sep 17 00:00:00 2001
From: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Date: Thu, 11 Aug 2016 16:29:12 +0200
Subject: [PATCH] Doc: Language edits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Task-number: QTBUG-53147
Change-Id: I353cf18b9661b5eb2371072f8091dc890fc7fcf0
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@theqtcompany.com>
---
.../compositor_api/qwaylandbufferref.cpp | 2 +-
.../compositor_api/qwaylandclient.cpp | 4 +-
.../compositor_api/qwaylandcompositor.cpp | 20 +++--
.../compositor_api/qwaylandinput.cpp | 2 +-
.../compositor_api/qwaylandkeyboard.cpp | 2 +-
.../compositor_api/qwaylandoutput.cpp | 80 ++++++++++---------
.../compositor_api/qwaylandpointer.cpp | 2 +-
.../qwaylandquickcompositor.cpp | 4 +-
.../compositor_api/qwaylandquickitem.cpp | 39 +++++----
.../compositor_api/qwaylandsurface.cpp | 38 +++++----
.../compositor_api/qwaylandview.cpp | 49 ++++++------
.../doc/src/qtwaylandcompositor-overview.qdoc | 34 ++++----
.../qwaylandquickshellsurfaceitem.cpp | 10 ++-
src/compositor/extensions/qwaylandwlshell.cpp | 28 +++----
.../extensions/qwaylandxdgshell.cpp | 4 +-
15 files changed, 167 insertions(+), 151 deletions(-)
diff --git a/src/compositor/compositor_api/qwaylandbufferref.cpp b/src/compositor/compositor_api/qwaylandbufferref.cpp
index e9fbcfbd..624deaff 100644
--- a/src/compositor/compositor_api/qwaylandbufferref.cpp
+++ b/src/compositor/compositor_api/qwaylandbufferref.cpp
@@ -56,7 +56,7 @@ public:
* \class QWaylandBufferRef
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief A class which holds a reference to a surface buffer
+ * \brief The QWaylandBufferRef class holds the reference to a surface buffer
*
* This class can be used to reference a surface buffer. As long as a reference
* to the buffer exists, it is owned by the compositor and the client cannot modify it.
diff --git a/src/compositor/compositor_api/qwaylandclient.cpp b/src/compositor/compositor_api/qwaylandclient.cpp
index 044977b5..fbf8c127 100644
--- a/src/compositor/compositor_api/qwaylandclient.cpp
+++ b/src/compositor/compositor_api/qwaylandclient.cpp
@@ -88,7 +88,7 @@ public:
* \qmltype WaylandClient
* \inqmlmodule QtWayland.Compositor
* \preliminary
- * \brief A client connecting to the WaylandCompositor.
+ * \brief Represents a client connecting to the WaylandCompositor.
*
* This type represents a client connecting to the compositor using the Wayland protocol.
* It corresponds to the Wayland interface wl_client.
@@ -98,7 +98,7 @@ public:
* \class QWaylandClient
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief A client connecting to the QWaylandCompositor.
+ * \brief The QWaylandClient class represents a client connecting to the QWaylandCompositor.
*
* This class corresponds to a client connecting to the compositor using the Wayland protocol.
* It corresponds to the Wayland interface wl_client.
diff --git a/src/compositor/compositor_api/qwaylandcompositor.cpp b/src/compositor/compositor_api/qwaylandcompositor.cpp
index 2fd5ca43..7338f060 100644
--- a/src/compositor/compositor_api/qwaylandcompositor.cpp
+++ b/src/compositor/compositor_api/qwaylandcompositor.cpp
@@ -405,7 +405,7 @@ void QWaylandCompositorPrivate::loadServerBufferIntegration()
\qmltype WaylandCompositor
\inqmlmodule QtWayland.Compositor
\preliminary
- \brief Type managing the Wayland display server.
+ \brief Manages the Wayland display server.
The WaylandCompositor manages the connections to the clients, as well as the different
\l{WaylandOutput}{outputs} and \l{QWaylandInputDevice}{input devices}.
@@ -424,7 +424,7 @@ void QWaylandCompositorPrivate::loadServerBufferIntegration()
\class QWaylandCompositor
\inmodule QtWaylandCompositor
\preliminary
- \brief Class managing the Wayland display server.
+ \brief The QWaylandCompositor class manages the Wayland display server.
The QWaylandCompositor manages the connections to the clients, as well as the different \l{QWaylandOutput}{outputs}
and \l{QWaylandInputDevice}{input devices}.
@@ -483,9 +483,8 @@ bool QWaylandCompositor::isCreated() const
* clients. It must be set before the component is completed.
*
* If the socketName is empty (the default), the contents of the start argument
- * --wayland-socket-name is used instead. If this is not set, then the compositor
- * will try to find a socket name automatically, which in the default case will
- * be "wayland-0".
+ * \c --wayland-socket-name are used instead. If the argument is not set, the
+ * compositor tries to find a socket name, which is \c{wayland-0} by default.
*/
/*!
@@ -495,9 +494,8 @@ bool QWaylandCompositor::isCreated() const
* clients. This must be set before the QWaylandCompositor is \l{create()}{created}.
*
* If the socketName is empty (the default), the contents of the start argument
- * --wayland-socket-name is used instead. If this is not set, then the compositor
- * will try to find a socket name automatically, which in the default case will
- * be "wayland-0".
+ * \c --wayland-socket-name are used instead. If the argument is not set, the
+ * compositor tries to find a socket name, which is \c{wayland-0} by default.
*/
void QWaylandCompositor::setSocketName(const QByteArray &name)
{
@@ -832,11 +830,11 @@ void QWaylandCompositor::setUseHardwareIntegrationExtension(bool use)
/*!
* Grab the surface content from the given \a buffer.
* The default implementation requires a OpenGL context to be bound to the current thread
- * to work. If this is not possible reimplement this function in your compositor subclass
- * to implement custom logic.
+ * to work. If this is not possible, reimplement this function in your compositor subclass
+ * to implement a custom logic.
* The default implementation only grabs SHM and OpenGL buffers, reimplement this in your
* compositor subclass to handle more buffer types.
- * You should not call this manually, but rather use QWaylandSurfaceGrabber (\a grabber).
+ * \note You should not call this manually, but rather use QWaylandSurfaceGrabber (\a grabber).
*/
void QWaylandCompositor::grabSurface(QWaylandSurfaceGrabber *grabber, const QWaylandBufferRef &buffer)
{
diff --git a/src/compositor/compositor_api/qwaylandinput.cpp b/src/compositor/compositor_api/qwaylandinput.cpp
index 4c2a0b43..a3bb6872 100644
--- a/src/compositor/compositor_api/qwaylandinput.cpp
+++ b/src/compositor/compositor_api/qwaylandinput.cpp
@@ -152,7 +152,7 @@ QWaylandKeymap::QWaylandKeymap(const QString &layout, const QString &variant, co
* \class QWaylandInputDevice
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief The QWaylandInputDevice class provides access to keyboard, mouse and touch input.
+ * \brief The QWaylandInputDevice class represents an input device such as a keyboard, mouse, and touch input.
*
* The QWaylandInputDevice provides access to different types of user input and maintains
* a keyboard focus and a mouse pointer. It corresponds to the wl_seat interface in the Wayland protocol.
diff --git a/src/compositor/compositor_api/qwaylandkeyboard.cpp b/src/compositor/compositor_api/qwaylandkeyboard.cpp
index e6ba64ed..22870654 100644
--- a/src/compositor/compositor_api/qwaylandkeyboard.cpp
+++ b/src/compositor/compositor_api/qwaylandkeyboard.cpp
@@ -382,7 +382,7 @@ void QWaylandKeyboardPrivate::sendRepeatInfo()
* \class QWaylandKeyboard
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief The QWaylandKeyboard class provides access to a keyboard device.
+ * \brief The QWaylandKeyboard class represents a keyboard device.
*
* This class provides access to the keyboard device in a QWaylandInputDevice. It corresponds to
* the Wayland interface wl_keyboard.
diff --git a/src/compositor/compositor_api/qwaylandoutput.cpp b/src/compositor/compositor_api/qwaylandoutput.cpp
index 65bac335..a2ebf8b2 100644
--- a/src/compositor/compositor_api/qwaylandoutput.cpp
+++ b/src/compositor/compositor_api/qwaylandoutput.cpp
@@ -190,32 +190,32 @@ QWaylandOutput::QWaylandOutput()
\qmltype WaylandOutput
\inqmlmodule QtWayland.Compositor
\preliminary
- \brief Type providing access to a displayable area managed by the compositor.
+ \brief Provides access to a displayable area managed by the compositor.
- The WaylandOutput manages a rectangular part of the compositor's geometry that
- can be used for displaying client content. This could, for instance, be a screen
- managed by the WaylandCompositor.
+ The WaylandOutput manages a rectangular area within bounds of the compositor's
+ geometry, to use it for displaying client content. This could, for instance, be
+ a screen managed by the WaylandCompositor.
- The type corresponds to the wl_output interface in the Wayland protocol.
+ The type corresponds to the \c wl_output interface in the Wayland protocol.
*/
/*!
\class QWaylandOutput
\inmodule QtWaylandCompositor
\preliminary
- \brief The QWaylandOutput class provides access to a displayable area managed by the compositor.
+ \brief The QWaylandOutput class represents a displayable area managed by the compositor.
- The QWaylandOutput manages a rectangular part of the compositor's geometry that
- can be used for displaying client content. This could, for instance, be a screen
- managed by the QWaylandCompositor.
+ The QWaylandOutput manages a rectangular area within bounds of the compositor's
+ geometry, to use it for displaying client content. This could, for instance, be
+ a screen managed by the WaylandCompositor.
- The class corresponds to the wl_output interface in the Wayland protocol.
+ The class corresponds to the \c wl_output interface in the Wayland protocol.
*/
/*!
* Constructs a QWaylandOutput in \a compositor and with the specified \a window. The
- * \l{QWaylandCompositor::create()}{create()} function must have been called on the
- * \a compositor before a QWaylandOutput is constructed for it.
+ * \l{QWaylandCompositor::create()}{create()} function must be called on the
+ * \a compositor before constructing a QWaylandOutput for it.
*
* The QWaylandOutput object is initialized later, in reaction to an event.
* At this point it is added as an output for the \a compositor. If it is the
@@ -307,8 +307,10 @@ void QWaylandOutput::update()
/*!
* \qmlproperty object QtWaylandCompositor::WaylandOutput::compositor
*
- * This property holds the compositor displaying content on this QWaylandOutput.
- * This property can only be set once, before the WaylandOutput component is completed.
+ * This property holds the compositor displaying content on this WaylandOutput.
+ *
+ * \note This property can be set only once, before the WaylandOutput component
+ * is completed.
*/
/*!
@@ -643,14 +645,14 @@ void QWaylandOutput::setSubpixel(const Subpixel &subpixel)
*
* This enum type is used to specify the orientation of a QWaylandOutput.
*
- * \value TransformNormal The QWaylandOutput orientation is normal.
- * \value Transform90 The QWaylandOutput is rotated 90 degrees.
- * \value Transform180 The QWaylandOutput is rotated 180 degrees.
- * \value Transform270 The QWaylandOutput is rotated 270 degrees.
- * \value TransformFlipped The QWaylandOutput is mirrored.
- * \value TransformFlipped90 The QWaylandOutput is mirrored, and rotated 90 degrees.
- * \value TransformFlipped180 The QWaylandOutput is mirrored, and rotated 180 degrees.
- * \value TransformFlipped270 The QWaylandOutput is mirrored, and rotated 270 degrees.
+ * \value TransformNormal The orientation is normal.
+ * \value Transform90 The orientation is rotated 90 degrees.
+ * \value Transform180 The orientation is rotated 180 degrees.
+ * \value Transform270 The orientation is rotated 270 degrees.
+ * \value TransformFlipped The orientation is mirrored.
+ * \value TransformFlipped90 The orientation is mirrored, and rotated 90 degrees.
+ * \value TransformFlipped180 The orientation is mirrored, and rotated 180 degrees.
+ * \value TransformFlipped270 The orientation is mirrored, and rotated 270 degrees.
*
* \sa QWaylandOutput::transform
*/
@@ -662,14 +664,14 @@ void QWaylandOutput::setSubpixel(const Subpixel &subpixel)
* to compensate for the orientation of the QWaylandOutput.
*
* \list
- * \li WaylandOutput.TransformNormal The QWaylandOutput orientation is normal.
- * \li WaylandOutput.Transform90 The QWaylandOutput is rotated 90 degrees.
- * \li WaylandOutput.Transform180 The QWaylandOutput is rotated 180 degrees.
- * \li WaylandOutput.Transform270 The QWaylandOutput is rotated 270 degrees.
- * \li WaylandOutput.TransformFlipped The QWaylandOutput is mirrored.
- * \li WaylandOutput.TransformFlipped90 The QWaylandOutput is mirrored, then rotated 90 degrees.
- * \li WaylandOutput.TransformFlipped180 The QWaylandOutput is mirrored, then rotated 180 degrees.
- * \li WaylandOutput.TransformFlipped270 The QWaylandOutput is mirrored, then rotated 270 degrees.
+ * \li WaylandOutput.TransformNormal The orientation is normal.
+ * \li WaylandOutput.Transform90 The orientation is rotated 90 degrees.
+ * \li WaylandOutput.Transform180 The orientation is rotated 180 degrees.
+ * \li WaylandOutput.Transform270 The orientation is rotated 270 degrees.
+ * \li WaylandOutput.TransformFlipped The orientation is mirrored.
+ * \li WaylandOutput.TransformFlipped90 The orientation is mirrored, then rotated 90 degrees.
+ * \li WaylandOutput.TransformFlipped180 The orientation is mirrored, then rotated 180 degrees.
+ * \li WaylandOutput.TransformFlipped270 The orientation is mirrored, then rotated 270 degrees.
* \endlist
*
* The default is WaylandOutput.TransformNormal.
@@ -705,7 +707,7 @@ void QWaylandOutput::setTransform(const Transform &transform)
* \qmlproperty int QtWaylandCompositor::WaylandOutput::scaleFactor
*
* This property holds the factor by which the WaylandCompositor scales surface buffers
- * before they are displayed. This is used on high density output devices where unscaled content
+ * before they are displayed. It is used on high density output devices where unscaled content
* would be too small to be practical. The client can in turn set the scale factor of its
* buffer to match the output if it prefers to provide high resolution content that is
* suitable for the output device.
@@ -753,7 +755,7 @@ void QWaylandOutput::setScaleFactor(int scale)
* This property controls whether the size of the WaylandOutput matches the
* size of its window.
*
- * The default is true if this WaylandOutput has a window.
+ * The default is \c true if this WaylandOutput has a window.
*/
/*!
@@ -762,7 +764,7 @@ void QWaylandOutput::setScaleFactor(int scale)
* This property controls whether the size of the QWaylandOutput matches the
* size of its window.
*
- * The default is true if this QWaylandOutput has a window.
+ * The default is \c true if this QWaylandOutput has a window.
*/
bool QWaylandOutput::sizeFollowsWindow() const
{
@@ -794,8 +796,10 @@ void QWaylandOutput::setSizeFollowsWindow(bool follow)
/*!
* \qmlproperty object QtWaylandCompositor::WaylandOutput::window
*
- * This property holds the Window for this WaylandOutput. This property can only be set once,
- * before the WaylandOutput component is completed.
+ * This property holds the Window for this WaylandOutput.
+ *
+ * \note This property can be set only once, before the WaylandOutput
+ * component is completed.
*/
/*!
@@ -822,7 +826,7 @@ void QWaylandOutput::setWindow(QWindow *window)
}
/*!
- * Tells the QWaylandOutput that a frame has started.
+ * Informs QWaylandOutput that a frame has started.
*/
void QWaylandOutput::frameStarted()
{
@@ -878,7 +882,7 @@ void QWaylandOutput::surfaceLeave(QWaylandSurface *surface)
}
/*!
- * This functions sets the width of this QWaylandOutput to \a newWidth.
+ * Sets the width of this QWaylandOutput to \a newWidth.
*
* \sa setHeight, QWaylandOutput::geometry
*/
@@ -894,7 +898,7 @@ void QWaylandOutput::setWidth(int newWidth)
}
/*!
- * This functions sets the height of this QWaylandOutput to \a newHeight.
+ * Sets the height of this QWaylandOutput to \a newHeight.
*
* \sa setWidth, QWaylandOutput::geometry
*/
diff --git a/src/compositor/compositor_api/qwaylandpointer.cpp b/src/compositor/compositor_api/qwaylandpointer.cpp
index da08e339..5e977863 100644
--- a/src/compositor/compositor_api/qwaylandpointer.cpp
+++ b/src/compositor/compositor_api/qwaylandpointer.cpp
@@ -95,7 +95,7 @@ void QWaylandPointerPrivate::pointer_set_cursor(wl_pointer::Resource *resource,
* \class QWaylandPointer
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief The QWaylandPointer class provides access to a pointer device.
+ * \brief The QWaylandPointer class represents a pointer device.
*
* This class provides access to the pointer device in a QWaylandInputDevice. It corresponds to
* the Wayland interface wl_pointer.
diff --git a/src/compositor/compositor_api/qwaylandquickcompositor.cpp b/src/compositor/compositor_api/qwaylandquickcompositor.cpp
index dc13368f..64e6fec7 100644
--- a/src/compositor/compositor_api/qwaylandquickcompositor.cpp
+++ b/src/compositor/compositor_api/qwaylandquickcompositor.cpp
@@ -79,8 +79,8 @@ QWaylandQuickCompositor::QWaylandQuickCompositor(QObject *parent)
* any Wayland extension the compositor should support, instantiate its component,
* and add it to the list of extensions.
*
- * For instance, the following code would allow the clients to request wl shell surfaces
- * in the compositor using the wl_shell interface.
+ * For instance, the following code would allow the clients to request \c wl_shell
+ * surfaces in the compositor using the \c wl_shell interface.
*
* \code
* import QtWayland.Compositor 1.0
diff --git a/src/compositor/compositor_api/qwaylandquickitem.cpp b/src/compositor/compositor_api/qwaylandquickitem.cpp
index f9cf45ff..a1855529 100644
--- a/src/compositor/compositor_api/qwaylandquickitem.cpp
+++ b/src/compositor/compositor_api/qwaylandquickitem.cpp
@@ -333,10 +333,10 @@ private:
* \qmltype WaylandQuickItem
* \inqmlmodule QtWayland.Compositor
* \preliminary
- * \brief A Qt Quick item representing a WaylandView.
+ * \brief Provides a Qt Quick item that represents a WaylandView.
*
- * When writing a WaylandCompositor in Qt Quick, this type can be used to display a
- * client's contents on an output device and will pass user input to the
+ * Qt Quick-based Wayland compositors can use this type to display a client's
+ * contents on an output device. It passes user input to the
* client.
*/
@@ -344,7 +344,7 @@ private:
* \class QWaylandQuickItem
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief A Qt Quick item representing a QWaylandView.
+ * \brief The QWaylandQuickItem class provides a Qt Quick item representing a QWaylandView.
*
* When writing a QWaylandCompositor in Qt Quick, this class can be used to display a
* client's contents on an output device and will pass user input to the
@@ -399,7 +399,7 @@ QWaylandCompositor *QWaylandQuickItem::compositor() const
}
/*!
- * \qmlproperty object QWaylandQuickItem::view
+ * \qmlproperty object QtWaylandCompositor::WaylandQuickItem::view
*
* This property holds the view rendered by this WaylandQuickItem.
*/
@@ -416,7 +416,7 @@ QWaylandView *QWaylandQuickItem::view() const
}
/*!
- * \qmlproperty object QWaylandQuickItem::surface
+ * \qmlproperty object QtWaylandCompositor::WaylandQuickItem::surface
*
* This property holds the surface rendered by this WaylandQuickItem.
*/
@@ -865,7 +865,7 @@ void QWaylandQuickItem::updateSize()
* This property specifies whether the WaylandQuickItem should take focus when
* it is clicked.
*
- * The default is true.
+ * The default is \c true.
*/
/*!
@@ -874,7 +874,7 @@ void QWaylandQuickItem::updateSize()
* This property specifies whether the QWaylandQuickItem should take focus when
* it is clicked.
*
- * The default is true.
+ * The default is \c true.
*/
bool QWaylandQuickItem::focusOnClick() const
{
@@ -893,7 +893,7 @@ void QWaylandQuickItem::setFocusOnClick(bool focus)
}
/*!
- * Returns true if the input region of this item's surface contains the
+ * Returns \c true if the input region of this item's surface contains the
* position given by \a localPosition.
*/
bool QWaylandQuickItem::inputRegionContains(const QPointF &localPosition)
@@ -910,7 +910,7 @@ bool QWaylandQuickItem::inputRegionContains(const QPointF &localPosition)
* This property specifies whether the size of the item should always match
* the size of its surface.
*
- * The default is true.
+ * The default is \c true.
*/
/*!
@@ -919,7 +919,7 @@ bool QWaylandQuickItem::inputRegionContains(const QPointF &localPosition)
* This property specifies whether the size of the item should always match
* the size of its surface.
*
- * The default is true.
+ * The default is \c true.
*/
bool QWaylandQuickItem::sizeFollowsSurface() const
{
@@ -957,12 +957,19 @@ QVariant QWaylandQuickItem::inputMethodQuery(Qt::InputMethodQuery query, QVarian
#endif
/*!
- \qmlproperty bool QtWayland::QWaylandSurfaceItem::paintEnabled
+ \qmlproperty bool QtWaylandCompositor::WaylandQuickItem::paintEnabled
+
+ If this property is \c true, the item is hidden, though the texture
+ is still updated. As opposed to hiding the item by
+ setting \l{Item::visible}{visible} to \c false, setting this property to \c true
+ will not prevent mouse or keyboard input from reaching item.
+*/
- If this property is true, the \l item is hidden, though the texture
- will still be updated. As opposed to hiding the \l item by
- setting \l{Item::visible}{visible} to false, setting this property to true
- will not prevent mouse or keyboard input from reaching \l item.
+/*!
+ If this property is \c true, the item is hidden, though the texture
+ is still updated. As opposed to hiding the item by
+ setting \l{Item::visible}{visible} to \c false, setting this property to \c true
+ will not prevent mouse or keyboard input from reaching item.
*/
bool QWaylandQuickItem::paintEnabled() const
{
diff --git a/src/compositor/compositor_api/qwaylandsurface.cpp b/src/compositor/compositor_api/qwaylandsurface.cpp
index c4c004b2..edb34e0b 100644
--- a/src/compositor/compositor_api/qwaylandsurface.cpp
+++ b/src/compositor/compositor_api/qwaylandsurface.cpp
@@ -378,20 +378,20 @@ QtWayland::SurfaceBuffer *QWaylandSurfacePrivate::createSurfaceBuffer(struct ::w
* \qmltype WaylandSurface
* \inqmlmodule QtWayland.Compositor
* \preliminary
- * \brief A rectangular area which is displayed on an output device.
+ * \brief Represents a rectangular area on an output device.
*
* This type encapsulates a rectangular area of pixels that is displayed on an output device. It
- * corresponds to the interface wl_surface in the Wayland protocol.
+ * corresponds to the interface \c wl_surface in the Wayland protocol.
*/
/*!
* \class QWaylandSurface
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief A rectangular area which is displayed on an output device.
+ * \brief The QWaylandSurface class represents a rectangular area on an output device.
*
* This class encapsulates a rectangular area of pixels that is displayed on an output device. It
- * corresponds to the interface wl_surface in the Wayland protocol.
+ * corresponds to the interface \c wl_surface in the Wayland protocol.
*/
/*!
@@ -433,7 +433,7 @@ QWaylandSurface::~QWaylandSurface()
/*!
* \qmlmethod void QtWaylandCompositor::WaylandSurface::initialize(object compositor, object client, int id, int version)
*
- * Initializes the QWaylandSurface with the given \a compositor and \a client, and with the given \a id
+ * Initializes the WaylandSurface with the given \a compositor and \a client, and with the given \a id
* and \a version.
*/
@@ -466,7 +466,7 @@ bool QWaylandSurface::isInitialized() const
/*!
* \qmlproperty object QtWaylandCompositor::WaylandSurface::client
*
- * This property holds the client using this QWaylandSurface.
+ * This property holds the client using this WaylandSurface.
*/
/*!
@@ -543,7 +543,7 @@ int QWaylandSurface::bufferScale() const
*
* This property holds the orientation of the WaylandSurface's contents.
*
- * \sa QWaylandOutput::transform
+ * \sa {WaylandOutput::transform}{WaylandOutput.transform}
*/
/*!
@@ -632,8 +632,8 @@ void QWaylandSurface::sendFrameCallbacks()
}
/*!
- * Returns true if the QWaylandSurface's input region contains the point \a p.
- * Otherwise returns false.
+ * Returns \c true if the QWaylandSurface's input region contains the point \a p.
+ * Otherwise returns \c false.
*/
bool QWaylandSurface::inputRegionContains(const QPoint &p) const
{
@@ -644,7 +644,7 @@ bool QWaylandSurface::inputRegionContains(const QPoint &p) const
/*!
* \qmlmethod void QtWaylandCompositor::WaylandSurface::destroy()
*
- * Destroys the QWaylandSurface.
+ * Destroys the WaylandSurface.
*/
/*!
@@ -659,7 +659,7 @@ void QWaylandSurface::destroy()
/*!
* \qmlmethod bool QtWaylandCompositor::WaylandSurface::isDestroyed()
*
- * Returns true if the WaylandSurface has been destroyed. Otherwise returns false.
+ * Returns \c true if the WaylandSurface has been destroyed. Otherwise returns \c false.
*/
/*!
@@ -701,9 +701,9 @@ QWaylandInputMethodControl *QWaylandSurface::inputMethodControl() const
}
/*!
- * Updates the surface with the compositor's retained clipboard selection. While this
- * is done automatically when the surface receives keyboard focus, this function is
- * useful for updating clients which do not have keyboard focus.
+ * Updates the surface with the compositor's retained clipboard selection. Although
+ * this is done automatically when the surface receives keyboard focus, this
+ * function is useful for updating clients which do not have keyboard focus.
*/
void QWaylandSurface::updateSelection()
{
@@ -784,13 +784,11 @@ struct wl_resource *QWaylandSurface::resource() const
}
/*!
- * Sets a role on the surface. A role defines how a surface will be mapped on screen, without a role
- * a surface is supposed to be hidden. Only one role at all times can be set on a surface. Attempting
- * to change the role of a surface will trigger a protocol error to the client, while setting the same
- * role many times is allowed.
+ * Sets a \a role on the surface. A role defines how a surface will be mapped on screen, without a role
+ * a surface is supposed to be hidden. Only one role at all times can be set on a surface. Although
+ * setting the same role many times is allowed, attempting to change the role of a surface will trigger
+ * a protocol error to the \a errorResource and send an \a errorCode to the client.
*
- * \param errorResource The resource the error will be sent to if the role is being changed.
- * \param errorCode The error code that will be sent to the client.
*/
bool QWaylandSurface::setRole(QWaylandSurfaceRole *role, wl_resource *errorResource, uint32_t errorCode)
{
diff --git a/src/compositor/compositor_api/qwaylandview.cpp b/src/compositor/compositor_api/qwaylandview.cpp
index 6c1ce248..12b67bf5 100644
--- a/src/compositor/compositor_api/qwaylandview.cpp
+++ b/src/compositor/compositor_api/qwaylandview.cpp
@@ -62,18 +62,20 @@ void QWaylandViewPrivate::markSurfaceAsDestroyed(QWaylandSurface *surface)
* \preliminary
* \brief Represents a view of a surface on an output.
*
- * The WaylandView corresponds to the presentation of a surface on a specific output, managing
- * the buffers that contain the contents to be rendered. You can have several views into the same surface.
+ * The WaylandView corresponds to the presentation of a surface on a specific
+ * output, managing the buffers that contain the contents to be rendered.
+ * You can have several views into the same surface.
*/
/*!
* \class QWaylandView
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief Represents a view of a surface on an output.
+ * \brief The QWaylandView class represents a view of a surface on an output.
*
- * The WaylandView corresponds to the presentation of a surface on a specific output, managing
- * the buffers that contain the contents to be rendered. You can have several views into the same surface.
+ * The QWaylandView corresponds to the presentation of a surface on a specific
+ * output, managing the buffers that contain the contents to be rendered.
+ * You can have several views into the same surface.
*/
/*!
@@ -162,7 +164,7 @@ void QWaylandView::setSurface(QWaylandSurface *newSurface)
}
/*!
- * \qmlproperty object QtWaylandCompositor::WaylandView::surface
+ * \qmlproperty object QtWaylandCompositor::WaylandView::output
*
* This property holds the output on which this view displays its surface.
*/
@@ -196,8 +198,8 @@ void QWaylandView::setOutput(QWaylandOutput *newOutput)
}
/*!
- * Attaches a new buffer \a ref and \a damage region to this QWaylandView. These
- * will become current the next time advance() is called.
+ * Attaches a new buffer \a ref and a \a damage region to this QWaylandView. These
+ * will become current on a subsequent call to the advance() method.
*/
void QWaylandView::attach(const QWaylandBufferRef &ref, const QRegion &damage)
{
@@ -208,21 +210,20 @@ void QWaylandView::attach(const QWaylandBufferRef &ref, const QRegion &damage)
}
/*!
- * Sets the next buffer and damage to current and returns true. If the buffer
+ * Sets the next buffer and damage region to current and returns \c true. If the buffer
* is locked or if no new buffer has been attached since the last call to
- * advance(), the function returns false and does nothing.
+ * advance(), the function returns \c false and does nothing.
*
- * If this view is set as its surface's throttling view, discardCurrentBuffer()
- * will be called on all views of the same surface for which the
+ * If this view is set as the surface's throttling view, discardCurrentBuffer()
+ * is called on all views of the same surface for which the
* \l{QWaylandView::discardFrontBuffers}{discardFrontBuffers}
* property is set to true and the current buffer is the same as the
* throttling view's current buffer.
*
- * This allows for a design where a primary
- * view can make sure that views running on a lower frequency will release their
- * front buffer references so that the buffer can be reused on the client side,
- * avoiding the situation where the lower frequency views throttle the frame rate
- * of the client application.
+ * To enable clients to reuse existing buffers, enable the primary view to ensure
+ * that views running on a lower frequency will release their front buffer
+ * references. This design approach should avoid the situation where the lower
+ * frequency views throttle the frame rate of the client application.
*/
bool QWaylandView::advance()
{
@@ -282,20 +283,20 @@ QRegion QWaylandView::currentDamage()
* \qmlproperty bool QtWaylandCompositor::WaylandView::bufferLock
*
* This property holds whether the view's buffer is currently locked. When
- * the buffer is locked, advance() will not advance to the next buffer,
- * but will instead return false.
+ * the buffer is locked, advance() will not advance to the next buffer and
+ * returns \c false.
*
- * The default is false.
+ * The default is \c false.
*/
/*!
* \property QWaylandView::bufferLock
*
* This property holds whether the view's buffer is currently locked. When
- * the buffer is locked, advance() will not advance to the next buffer,
- * but will instead return false.
+ * the buffer is locked, advance() will not advance to the next buffer
+ * and returns \c false.
*
- * The default is false.
+ * The default is \c false.
*/
bool QWaylandView::isBufferLocked() const
{
@@ -321,7 +322,7 @@ void QWaylandView::setBufferLock(bool locked)
* \property QWaylandView::discardFrontBuffers
*
* By default, the view locks the current buffer until advance() is called. Set this property
- * to true to allow Qt to release the buffer when the throttling view is no longer using it.
+ * to \c true to allow Qt to release the buffer when the throttling view is no longer using it.
*/
bool QWaylandView::discardFrontBuffers() const
{
diff --git a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
index 9811d520..d2f0f6f4 100644
--- a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
+++ b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
@@ -30,25 +30,31 @@
\title Qt Wayland Compositor
\brief An API to develop display servers supporting the Wayland protocol
- Qt Wayland Compositor is a module consisting of QML and C++ APIs for developing
- custom display servers based on the \l{http://wayland.freedesktop.org}{Wayland protocol}.
- The server displays content from client applications that support the Wayland protocol.
+ Qt Wayland Compositor is a module that provides QML and C++ APIs for
+ developing custom display servers based on the
+ \l{http://wayland.freedesktop.org}{Wayland protocol}. The server displays
+ content from client applications that support the Wayland protocol.
\section1 Environment Variables and Command-line Arguments
- The Qt Wayland Compositor API recognizes some environment variables and command-line arguments
- that can be used to customize its behavior.
+ The Qt Wayland Compositor API recognizes some environment variables and
+ command-line arguments that can be used to customize its behavior.
- The environment variables:
\list
- \li QT_WAYLAND_HARDWARE_INTEGRATION Selects which hardware integration plugin to use.
- \li QT_WAYLAND_CLIENT_BUFFER_INTEGRATION Selects which client buffer integration plugin to use.
- \li QT_WAYLAND_SERVER_BUFFER_INTEGRATION Selects which server integration plugin to use.
- \endlist
-
- The command-line arguments:
- \list
- \li --wayland-socket-name Overrides the default socket name used for communicating with clients.
+ \li Environment variables:
+ \list
+ \li \b QT_WAYLAND_HARDWARE_INTEGRATION Selects the hardware integration
+ plugin to use.
+ \li \b QT_WAYLAND_CLIENT_BUFFER_INTEGRATION Selects the client buffer
+ integration plugin to use.
+ \li \b QT_WAYLAND_SERVER_BUFFER_INTEGRATION Selects the server
+ integration plugin to use.
+ \endlist
+ \li Command-line arguments:
+ \list
+ \li \c{--wayland-socket-name} Overrides the default socket name used for
+ communicating with clients.
+ \endlist
\endlist
\section1 Examples
diff --git a/src/compositor/extensions/qwaylandquickshellsurfaceitem.cpp b/src/compositor/extensions/qwaylandquickshellsurfaceitem.cpp
index 5fe43e54..9cb65fbe 100644
--- a/src/compositor/extensions/qwaylandquickshellsurfaceitem.cpp
+++ b/src/compositor/extensions/qwaylandquickshellsurfaceitem.cpp
@@ -46,19 +46,21 @@ QT_BEGIN_NAMESPACE
* \qmltype ShellSurfaceItem
* \inqmlmodule QtWayland.Compositor
* \preliminary
- * \brief An item representing a WlShellSurface.
+ * \brief A Qt Quick item type representing a WlShellSurface.
*
- * This type is used to render wl_shell or xdg_shell surfaces as part of a Qt Quick
+ * This type is used to render \c wl_shell or \c xdg_shell surfaces as part of a Qt Quick
* scene. It handles moving and resizing triggered by clicking on the window decorations.
+ *
+ * \sa WaylandQuickItem
*/
/*!
* \class QWaylandQuickShellSurfaceItem
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief A Qt Quick item for QWaylandShellSurface.
+ * \brief The QWaylandQuickShellSurfaceItem class provides a Qt Quick item that represents a QWaylandShellSurface.
*
- * This class is used to render wl_shell or xdg_shell surfaces as part of a Qt Quick
+ * This class is used to render \c wl_shell or \c xdg_shell surfaces as part of a Qt Quick
* scene. It handles moving and resizing triggered by clicking on the window decorations.
*
* \sa QWaylandQuickItem
diff --git a/src/compositor/extensions/qwaylandwlshell.cpp b/src/compositor/extensions/qwaylandwlshell.cpp
index a4d98207..c79ddac7 100644
--- a/src/compositor/extensions/qwaylandwlshell.cpp
+++ b/src/compositor/extensions/qwaylandwlshell.cpp
@@ -243,13 +243,13 @@ void QWaylandWlShellSurfacePrivate::shell_surface_set_class(Resource *resource,
* \qmltype WlShell
* \inqmlmodule QtWayland.Compositor
* \preliminary
- * \brief Extension for desktop-style user interfaces.
+ * \brief Provides an extension for desktop-style user interfaces.
*
* The WlShell extension provides a way to assiociate a ShellSurface
* with a regular Wayland surface. Using the shell surface interface, the client
* can request that the surface is resized, moved, and so on.
*
- * WlShell corresponds to the Wayland interface wl_shell.
+ * WlShell corresponds to the Wayland interface \c wl_shell.
*
* To provide the functionality of the shell extension in a compositor, create
* an instance of the WlShell component and add it to the list of extensions
@@ -269,13 +269,13 @@ void QWaylandWlShellSurfacePrivate::shell_surface_set_class(Resource *resource,
* \class QWaylandWlShell
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief Extension for desktop-style user interfaces.
+ * \brief The QWaylandWlShell class is an extension for desktop-style user interfaces.
*
* The QWaylandWlShell extension provides a way to assiociate a QWaylandWlShellSurface with
* a regular Wayland surface. Using the shell surface interface, the client
* can request that the surface is resized, moved, and so on.
*
- * WlShell corresponds to the Wayland interface wl_shell.
+ * WlShell corresponds to the Wayland interface \c wl_shell.
*/
/*!
@@ -319,8 +319,8 @@ const struct wl_interface *QWaylandWlShell::interface()
/*!
* \qmlsignal void QtWaylandCompositor::WlShell::createShellSurface(object surface, object client, int id)
*
- * This signal is emitted when the \a client has requested a wl_shell_surface to be associated
- * with \a surface and be assigned the given \a id. The handler for this signal is
+ * This signal is emitted when the \a client has requested a \c wl_shell_surface to be associated
+ * with \a surface, which is identified by \a id. The handler for this signal is
* expected to create the shell surface and initialize it within the scope of the
* signal emission.
*/
@@ -343,26 +343,26 @@ QByteArray QWaylandWlShell::interfaceName()
* \qmltype WlShellSurface
* \inqmlmodule QtWayland.Compositor
* \preliminary
- * \brief A wl_shell_surface providing desktop-style compositor-specific features to a surface.
+ * \brief Provides a \c wl_shell_surface that offers desktop-style compositor-specific features to a surface.
*
* This type is part of the \l{WlShell} extension and provides a way to extend
* the functionality of an existing WaylandSurface with features specific to desktop-style
* compositors, such as resizing and moving the surface.
*
- * It corresponds to the Wayland interface wl_shell_surface.
+ * It corresponds to the Wayland interface \c wl_shell_surface.
*/
/*!
* \class QWaylandWlShellSurface
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief A shell surface providing desktop-style compositor-specific features to a surface.
+ * \brief The QWaylandWlShellSurface class provides desktop-style compositor-specific features to a surface.
*
* This class is part of the QWaylandWlShell extension and provides a way to extend
* the functionality of an existing QWaylandSurface with features specific to desktop-style
* compositors, such as resizing and moving the surface.
*
- * It corresponds to the Wayland interface wl_shell_surface.
+ * It corresponds to the Wayland interface \c wl_shell_surface.
*/
/*!
@@ -385,11 +385,11 @@ QWaylandWlShellSurface::QWaylandWlShellSurface(QWaylandWlShell *shell, QWaylandS
/*!
* \qmlmethod void QtWaylandCompositor::WlShellSurface::initialize(object shell, object surface, object client, int id)
*
- * Initializes the WlShellSurface, associating it with the given \a shell, \a surface, \a client, and \a id.
+ * Initializes the WlShellSurface with \a id and associates it with the given \a shell, \a surface, and \a client.
*/
/*!
- * Initializes the QWaylandWlShellSurface, associating it with the given \a shell, \a surface and \a resource.
+ * Initializes the QWaylandWlShellSurface and associates it with the given \a shell, \a surface, and \a resource.
*/
void QWaylandWlShellSurface::initialize(QWaylandWlShell *shell, QWaylandSurface *surface, const QWaylandResource &resource)
{
@@ -443,7 +443,7 @@ QSize QWaylandWlShellSurface::sizeForResize(const QSizeF &size, const QPointF &d
/*!
* \enum QWaylandWlShellSurface::ResizeEdge
*
- * This enum type provides a way to specify a specific edge or corner of
+ * This enum type provides a way to specify an edge or corner of
* the surface.
*
* \value NoneEdge No edge.
@@ -501,7 +501,7 @@ QWaylandQuickShellIntegration *QWaylandWlShellSurface::createIntegration(QWaylan
/*!
* \qmlproperty object QtWaylandCompositor::WlShellSurface::surface
*
- * This property holds the wl_surface associated with this WlShellSurface.
+ * This property holds the \c wl_surface associated with this WlShellSurface.
*/
/*!
diff --git a/src/compositor/extensions/qwaylandxdgshell.cpp b/src/compositor/extensions/qwaylandxdgshell.cpp
index 4618891d..b5346036 100644
--- a/src/compositor/extensions/qwaylandxdgshell.cpp
+++ b/src/compositor/extensions/qwaylandxdgshell.cpp
@@ -579,7 +579,7 @@ void QWaylandXdgShell::handleFocusChanged(QWaylandSurface *newSurface, QWaylandS
* \class QWaylandXdgSurface
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief An xdg surface providing desktop-style compositor-specific features to a surface.
+ * \brief The QWaylandXdgSurface class provides desktop-style compositor-specific features to an xdg surface.
*
* This class is part of the QWaylandXdgShell extension and provides a way to
* extend the functionality of an existing QWaylandSurface with features
@@ -927,7 +927,7 @@ QWaylandQuickShellIntegration *QWaylandXdgSurface::createIntegration(QWaylandQui
* \class QWaylandXdgPopup
* \inmodule QtWaylandCompositor
* \preliminary
- * \brief An xdg popup providing menus for an xdg surface
+ * \brief The QWaylandXdgPopup class provides menus for an xdg surface
*
* This class is part of the QWaylandXdgShell extension and provides a way to
* extend the functionality of an existing QWaylandSurface with features
--
GitLab