Commit 684b4b63 authored by Vlad Zahorodnii's avatar Vlad Zahorodnii
Browse files

Use more traditional doxygen style

Summary:
So far we were following a bit unique and rare doxygen comment style:

    /**
     * Contents of the comment.
     **/

Doxygen comments with this style look balanced and neat, but many people
that contribute to KWin don't follow this style. Instead, they prefer
more traditional doxygen comment style, i.e.

    /**
     * Contents of the comment.
     */

Reviewing such changes has been a bit frustrating for me (so selfish!)
and for other contributors.

This change switches doxygen comment style in KWin to a more traditional
style. The main reason for doing this is to make code review process easier
for new contributors as well us.

Reviewers: #kwin, davidedmundson

Reviewed By: #kwin, davidedmundson

Subscribers: kwin

Tags: #kwin

Differential Revision: https://phabricator.kde.org/D22812
parent f57f5831
This diff is collapsed.
......@@ -37,7 +37,7 @@ public:
/**
* Returns the size of the gamma ramp.
**/
*/
uint32_t size() const;
/**
......@@ -45,12 +45,12 @@ public:
*
* The returned pointer can be used for altering the red component
* in the gamma ramp.
**/
*/
uint16_t *red();
/**
* Returns pointer to the first red component in the gamma ramp.
**/
*/
const uint16_t *red() const;
/**
......@@ -58,12 +58,12 @@ public:
*
* The returned pointer can be used for altering the green component
* in the gamma ramp.
**/
*/
uint16_t *green();
/**
* Returns pointer to the first green component in the gamma ramp.
**/
*/
const uint16_t *green() const;
/**
......@@ -71,12 +71,12 @@ public:
*
* The returned pointer can be used for altering the blue component
* in the gamma ramp.
**/
*/
uint16_t *blue();
/**
* Returns pointer to the first blue component in the gamma ramp.
**/
*/
const uint16_t *blue() const;
private:
......@@ -86,7 +86,7 @@ private:
/**
* Generic output representation.
**/
*/
class KWIN_EXPORT AbstractOutput : public QObject
{
Q_OBJECT
......@@ -97,17 +97,17 @@ public:
/**
* Returns the human readable name of this output.
**/
*/
virtual QString name() const = 0;
/**
* Returns geometry of this output in device independent pixels.
**/
*/
virtual QRect geometry() const = 0;
/**
* Returns the approximate vertical refresh rate of this output, in mHz.
**/
*/
virtual int refreshRate() const = 0;
/**
......@@ -115,42 +115,42 @@ public:
* e.g. LVDS, or eDP.
*
* Default implementation returns @c false.
**/
*/
virtual bool isInternal() const;
/**
* Returns the ratio between physical pixels and logical pixels.
*
* Default implementation returns 1.
**/
*/
virtual qreal scale() const;
/**
* Returns the physical size of this output, in millimeters.
*
* Default implementation returns an invalid QSize.
**/
*/
virtual QSize physicalSize() const;
/**
* Returns the orientation of this output.
*
* Default implementation returns Qt::PrimaryOrientation.
**/
*/
virtual Qt::ScreenOrientation orientation() const;
/**
* Returns the size of the gamma lookup table.
*
* Default implementation returns 0.
**/
*/
virtual int gammaRampSize() const;
/**
* Sets the gamma ramp of this output.
*
* Returns @c true if the gamma ramp was successfully set.
**/
*/
virtual bool setGammaRamp(const GammaRamp &gamma);
private:
......
......@@ -51,7 +51,7 @@ namespace KWin
/**
* Generic output representation in a Wayland session
**/
*/
class KWIN_EXPORT AbstractWaylandOutput : public AbstractOutput
{
Q_OBJECT
......@@ -70,7 +70,7 @@ public:
}
/**
* The geometry of this output in global compositor co-ordinates (i.e scaled)
**/
*/
QRect geometry() const override;
QSize physicalSize() const override;
Qt::ScreenOrientation orientation() const override {
......@@ -79,7 +79,7 @@ public:
/**
* Current refresh rate in 1/ms.
**/
*/
int refreshRate() const override;
bool isInternal() const override {
......@@ -91,7 +91,7 @@ public:
/**
* This sets the changes and tests them against the specific output.
**/
*/
void setChanges(KWayland::Server::OutputChangeSet *changeset);
QPointer<KWayland::Server::OutputInterface> waylandOutput() const {
......@@ -103,7 +103,7 @@ public:
*
* This differs from updateDpms as it also removes the wl_output.
* The default is on.
**/
*/
void setEnabled(bool enable);
Q_SIGNALS:
......
......@@ -226,7 +226,7 @@ namespace KWin
* effect than fixing the focus chain and the return value of
* activeClient(). And of course, to propagate the active client to the
* world.
**/
*/
void Workspace::setActiveClient(AbstractClient* c)
{
if (active_client == c)
......@@ -289,7 +289,7 @@ void Workspace::setActiveClient(AbstractClient* c)
*
* @see setActiveClient
* @see requestFocus
**/
*/
void Workspace::activateClient(AbstractClient* c, bool force)
{
if (c == NULL) {
......@@ -340,7 +340,7 @@ void Workspace::activateClient(AbstractClient* c, bool force)
* Workspace::activateClient() instead.
*
* @see activateClient
**/
*/
void Workspace::requestFocus(AbstractClient* c, bool force)
{
takeActivity(c, force ? ActivityFocusForce : ActivityFocus);
......@@ -411,7 +411,7 @@ void Workspace::takeActivity(AbstractClient* c, ActivityFlags flags)
* the workspace activates another one.
*
* @note @p c may already be destroyed.
**/
*/
void Workspace::clientHidden(AbstractClient* c)
{
assert(!c->isShown(true) || !c->isOnCurrentDesktop() || !c->isOnCurrentActivity());
......@@ -706,7 +706,7 @@ void Workspace::clientAttentionChanged(AbstractClient* c, bool set)
* This is called inside kwin for every action with the window
* that qualifies for user interaction (clicking on it, activate it
* externally, etc.).
**/
*/
void Client::updateUserTime(xcb_timestamp_t time)
{
// copied in Group::updateUserTime
......
......@@ -49,7 +49,7 @@ public:
* Adds/removes client \a c to/from \a activity.
*
* Takes care of transients as well.
**/
*/
void toggleClientOnActivity(Client* c, const QString &activity, bool dont_activate);
QStringList running() const;
......@@ -66,18 +66,18 @@ Q_SIGNALS:
* This signal is emitted when the global
* activity is changed
* @param id id of the new current activity
**/
*/
void currentChanged(const QString &id);
/**
* This signal is emitted when a new activity is added
* @param id id of the new activity
**/
*/
void added(const QString &id);
/**
* This signal is emitted when the activity
* is removed
* @param id id of the removed activity
**/
*/
void removed(const QString &id);
private Q_SLOTS:
......
......@@ -93,7 +93,7 @@ public:
/**
* @internal
**/
*/
void retrieveHelpers();
private:
......
......@@ -101,7 +101,7 @@ Q_DECLARE_FLAGS(AdditionalWaylandInterfaces, AdditionalWaylandInterface)
* client side objects which can be used to create windows.
* @returns @c true if created successfully, @c false if there was an error
* @see destroyWaylandConnection
**/
*/
bool setupWaylandConnection(AdditionalWaylandInterfaces flags = AdditionalWaylandInterfaces());
/**
......@@ -188,7 +188,7 @@ void initXdgShellPopup(KWayland::Client::Surface *surface, KWayland::Client::Xdg
/**
* Creates a shared memory buffer of @p size in @p color and attaches it to the @p surface.
* The @p surface gets damaged and committed, thus it's rendered.
**/
*/
void render(KWayland::Client::Surface *surface, const QSize &size, const QColor &color, const QImage::Format &format = QImage::Format_ARGB32_Premultiplied);
/**
......@@ -199,29 +199,29 @@ void render(KWayland::Client::Surface *surface, const QImage &img);
/**
* Waits till a new ShellClient is shown and returns the created ShellClient.
* If no ShellClient gets shown during @p timeout @c null is returned.
**/
*/
ShellClient *waitForWaylandWindowShown(int timeout = 5000);
/**
* Combination of @link{render} and @link{waitForWaylandWindowShown}.
**/
*/
ShellClient *renderAndWaitForShown(KWayland::Client::Surface *surface, const QSize &size, const QColor &color, const QImage::Format &format = QImage::Format_ARGB32, int timeout = 5000);
/**
* Waits for the @p client to be destroyed.
**/
*/
bool waitForWindowDestroyed(AbstractClient *client);
/**
* Locks the screen and waits till the screen is locked.
* @returns @c true if the screen could be locked, @c false otherwise
**/
*/
bool lockScreen();
/**
* Unlocks the screen and waits till the screen is unlocked.
* @returns @c true if the screen could be unlocked, @c false otherwise
**/
*/
bool unlockScreen();
}
......
......@@ -45,7 +45,7 @@ Q_DECLARE_METATYPE(KWin::ElectricBorder)
/**
* This test verifies the NoGlobalShortcuts initialization flag
**/
*/
class NoGlobalShortcutsTest : public QObject
{
Q_OBJECT
......
......@@ -32,21 +32,21 @@ private slots:
* pointer to a deleted TabBoxClient.
*
* See bug #303840
**/
*/
void testLongestCaptionWithNullClient();
/**
* Tests the creation of the Client list for the case that
* there is no active Client, but that Clients actually exist.
*
* See BUG: 305449
**/
*/
void testCreateClientListNoActiveClient();
/**
* Tests the creation of the Client list for the case that
* the active Client is not in the Focus chain.
*
* See BUG: 306260
**/
*/
void testCreateClientListActiveClientNotInFocusChain();
};
......
......@@ -36,7 +36,7 @@ private slots:
* shown is not valid. That is accessing the Pointer
* to the Client returns an invalid QVariant.
* BUG: 304620
**/
*/
void testDontCrashUpdateOutlineNullClient();
};
......
......@@ -460,7 +460,7 @@ static const TransKey g_rgQtToSymX[] = {
{ Qt::Key_ydiaeresis, XKB_KEY_ydiaeresis, Qt::KeyboardModifiers() },
/*
* Numpad
**/
*/
{ Qt::Key_0, XKB_KEY_KP_0, Qt::KeypadModifier },
{ Qt::Key_1, XKB_KEY_KP_1, Qt::KeypadModifier },
{ Qt::Key_2, XKB_KEY_KP_2, Qt::KeypadModifier },
......
......@@ -34,7 +34,7 @@ namespace KWin {
/**
* Wrapper to create an 0,0x10,10 input only window for testing purposes
**/
*/
#ifndef NO_NONE_WINDOW
static xcb_window_t createWindow()
{
......@@ -50,7 +50,7 @@ static xcb_window_t createWindow()
/**
* casts XCB_WINDOW_NONE to uint32_t. Needed to make QCOMPARE working.
**/
*/
#ifndef NO_NONE_WINDOW
static uint32_t noneWindow()
{
......
......@@ -90,12 +90,12 @@ const long ClientWinMask = XCB_EVENT_MASK_KEY_PRESS | XCB_EVENT_MASK_KEY_RELEASE
/**
* \class Client client.h
* \brief The Client class encapsulates a window decoration frame.
**/
*/
/**
* This ctor is "dumb" - it only initializes data. All the real initialization
* is done in manage().
**/
*/
Client::Client()
: AbstractClient()
, m_client()
......@@ -188,7 +188,7 @@ Client::Client()
/**
* "Dumb" destructor.
**/
*/
Client::~Client()
{
if (m_killHelperPID && !::kill(m_killHelperPID, 0)) { // means the process is alive
......@@ -216,7 +216,7 @@ void Client::deleteClient(Client* c)
/**
* Releases the window. The client has done its job and the window is still existing.
**/
*/
void Client::releaseWindow(bool on_shutdown)
{
assert(!deleting);
......@@ -292,7 +292,7 @@ void Client::releaseWindow(bool on_shutdown)
/**
* Like releaseWindow(), but this one is called when the window has been already destroyed
* (E.g. The application closed it)
**/
*/
void Client::destroyClient()
{
assert(!deleting);
......@@ -584,7 +584,7 @@ void Client::detectGtkFrameExtents()
* re-layouts (e.g. when maximization state changes,
* the decoration may alter some borders, but the actual size
* of the decoration stays the same).
**/
*/
void Client::resizeDecoration()
{
triggerDecorationRepaint();
......@@ -740,7 +740,7 @@ void Client::finishCompositing(ReleaseReason releaseReason)
/**
* Returns whether the window is minimizable or not
**/
*/
bool Client::isMinimizable() const
{
if (isSpecialWindow() && !isTransient())
......@@ -980,7 +980,7 @@ void Client::updateVisibility()
/**
* Sets the client window's mapping state. Possible values are
* WithdrawnState, IconicState, NormalState.
**/
*/
void Client::exportMappingState(int s)
{
assert(m_client != XCB_WINDOW_NONE);
......@@ -1048,7 +1048,7 @@ void Client::internalKeep()
* Maps (shows) the client. Note that it is mapping state of the frame,
* not necessarily the client window itself (i.e. a shaded window is here
* considered mapped, even though it is in IconicState).
**/
*/
void Client::map()
{
// XComposite invalidates backing pixmaps on unmap (minimize, different
......@@ -1069,7 +1069,7 @@ void Client::map()
/**
* Unmaps the client. Again, this is about the frame.
**/
*/
void Client::unmap()
{
// Here it may look like a race condition, as some other client might try to unmap
......@@ -1097,7 +1097,7 @@ void Client::unmap()
* then it's hoped that there will be some other desktop above it *shrug*.
* Using normal shape would be better, but that'd affect other things, e.g. painting
* of the actual preview.
**/
*/
void Client::updateHiddenPreview()
{
if (hiddenPreview()) {
......@@ -1135,7 +1135,7 @@ void Client::sendClientMessage(xcb_window_t w, xcb_atom_t a, xcb_atom_t protocol
/**
* Returns whether the window may be closed (have a close button)
**/
*/
bool Client::isCloseable() const
{
return rules()->checkCloseable(m_motif.close() && !isSpecialWindow());
......@@ -1143,7 +1143,7 @@ bool Client::isCloseable() const
/**
* Closes the window by either sending a delete_window message or using XKill.
**/
*/
void Client::closeWindow()
{
if (!isCloseable())
......@@ -1163,7 +1163,7 @@ void Client::closeWindow()
/**
* Kills the window via XKill
**/
*/
void Client::killWindow()
{
qCDebug(KWIN_CORE) << "Client::killWindow():" << caption();
......@@ -1175,7 +1175,7 @@ void Client::killWindow()
/**
* Send a ping to the window using _NET_WM_PING if possible if it
* doesn't respond within a reasonable time, it will be killed.
**/
*/
void Client::pingWindow()
{
if (!info->supportsProtocol(NET::PingProtocol))
......@@ -1287,7 +1287,7 @@ void Client::doSetDesktop(int desktop, int was_desk)
*
* Note: If it was on all activities and you try to remove it from one, nothing will happen;
* I don't think that's an important enough use case to handle here.
**/
*/
void Client::setOnActivity(const QString &activity, bool enable)
{
#ifdef KWIN_BUILD_ACTIVITIES
......@@ -1313,7 +1313,7 @@ void Client::setOnActivity(const QString &activity, bool enable)
/**
* set exactly which activities this client is on
**/
*/
void Client::setOnActivities(QStringList newActivitiesList)
{
#ifdef KWIN_BUILD_ACTIVITIES
......@@ -1370,7 +1370,7 @@ void Client::blockActivityUpdates(bool b)
/**
* update after activities changed
**/
*/
void Client::updateActivities(bool includeTransients)
{
if (m_activityUpdatesBlocked) {
......@@ -1392,7 +1392,7 @@ void Client::updateActivities(bool includeTransients)
* Returns the list of activities the client window is on.
* if it's on all activities, the list will be empty.
* Don't use this, use isOnActivity() and friends (from class Toplevel)
**/
*/
QStringList Client::activities() const
{
if (sessionActivityOverride) {
......@@ -1404,7 +1404,7 @@ QStringList Client::activities() const
/**
* if @p on is true, sets on all activities.
* if it's false, sets it to only be on the current activity
**/
*/
void Client::setOnAllActivities(bool on)
{
#ifdef KWIN_BUILD_ACTIVITIES
......@@ -1423,7 +1423,7 @@ void Client::setOnAllActivities(bool on)
/**
* Performs the actual focusing of the window using XSetInputFocus and WM_TAKE_FOCUS
**/
*/
void Client::takeFocus()
{
if (rules()->checkAcceptFocus(info->input()))
......@@ -1454,7 +1454,7 @@ void Client::takeFocus()
* contextHelp() if this is invoked.
*
* \sa contextHelp()
**/
*/
bool Client::providesContextHelp() const
{
return info->supportsProtocol(NET::ContextHelpProtocol);
......@@ -1465,7 +1465,7 @@ bool Client::providesContextHelp() const
* actually provides context help.
*
* \sa providesContextHelp()
**/
*/
void Client::showContextHelp()
{
if (info->supportsProtocol(NET::ContextHelpProtocol)) {
......@@ -1476,7 +1476,7 @@ void Client::showContextHelp()
/**
* Fetches the window's caption (WM_NAME property). It will be
* stored in the client's caption().
**/
*/
void Client::fetchName()
{
setCaption(readName());
......@@ -1733,7 +1733,7 @@ void Client::getSyncCounter()
/**
* Send the client a _NET_SYNC_REQUEST
**/
*/
void Client::sendSyncRequest()
{
if (syncRequest.counter == XCB_NONE || syncRequest.isPending)
......
......@@ -51,7 +51,7 @@ namespace KWin
* @brief Defines Predicates on how to search for a Client.
*
* Used by Workspace::findClient.
**/
*/
enum class Predicate {
WindowMatch,
WrapperIdMatch,
......@@ -68,7 +68,7 @@ class KWIN_EXPORT Client
* MAY BE DISOBEYED BY THE WM! It's only for information, do NOT rely on it at all.
* The value is evaluated each time the getter is called.
* Because of that no changed signal is provided.
**/
*/
Q_PROPERTY(QSize basicUnit READ basicUnit)
/**
* A client can block compositing. That is while the Client is alive and the state is set,
......@@ -79,12 +79,12 @@ class KWIN_EXPORT Client
* group. For convenience it's exported as a property to the scripts.
*
* Use with care!
**/
*/
Q_PROPERTY(bool blocksCompositing READ isBlockingCompositing WRITE setBlockingCompositing NOTIFY blockingCompositingChanged)
/**
* Whether the Client uses client side window decorations.
* Only GTK+ are detected.
**/
*/
Q_PROPERTY(bool clientSideDecorated READ isClientSideDecorated NOTIFY clientSideDecoratedChanged)
public:
explicit Client();
......@@ -253,13 +253,13 @@ public:
* the client is unmapped and hidden, this function is called
* when the tabbing group of the client switches its visible
* client.
**/
*/
void setClientShown(bool shown) override;
/**
* Whether or not the window has a strut that expands through the invisible area of
* an xinerama setup where the monitors are not the same resolution.
**/
*/
bool hasOffscreenXineramaStrut() const;
// Decorations <-> Effects
......@@ -291,7 +291,7 @@ public:
/**
* Restores the Client after it had been hidden due to show on screen edge functionality.
* In addition the property gets deleted so that the Client knows that it is visible again.
**/
*/
void showOnScreenEdge() override;
Xcb::StringProperty fetchApplicationMenuServiceName() const;
......@@ -381,24 +381,24 @@ Q_SIGNALS:
/**
* Emitted whenever the Client want to show it menu