Commit 7b20e1f6 authored by Vlad Zahorodnii's avatar Vlad Zahorodnii

Overhaul doxygen comments

Summary:
We have a mix of different doxygen comment styles, e.g.

    /*!
      Foo bar.
     */

    /**
     * Foo bar.
     */

    /** Foo bar.
     */

    /**
     * Foo bar.
     */

    /**
     * Foo bar.
     **/

To make the code more consistent, this change updates the style of all
doxygen comments to the last one.

Test Plan: Compiles.

Reviewers: #kwin, davidedmundson

Reviewed By: #kwin, davidedmundson

Subscribers: kwin

Tags: #kwin

Differential Revision: https://phabricator.kde.org/D18683
parent 31dcf51c
......@@ -264,11 +264,11 @@ class KWIN_EXPORT AbstractClient : public Toplevel
/**
* Whether an application menu is available for this Client
*/
**/
Q_PROPERTY(bool hasApplicationMenu READ hasApplicationMenu NOTIFY hasApplicationMenuChanged)
/**
* Whether the application menu for this Client is currently opened
*/
**/
Q_PROPERTY(bool applicationMenuActive READ applicationMenuActive NOTIFY applicationMenuActiveChanged)
/**
......@@ -276,7 +276,7 @@ class KWIN_EXPORT AbstractClient : public Toplevel
*
* When an application failed to react on a ping request in time, it is
* considered unresponsive. This usually indicates that the application froze or crashed.
*/
**/
Q_PROPERTY(bool unresponsive READ unresponsive NOTIFY unresponsiveChanged)
/**
* The "Window Tabs" Group this Client belongs to.
......@@ -288,7 +288,7 @@ class KWIN_EXPORT AbstractClient : public Toplevel
* Absolute file path, or name of palette in the user's config directory following KColorSchemes format.
* An empty string indicates the default palette from kdeglobals is used.
* @note this indicates the colour scheme requested, which might differ from the theme applied if the colorScheme cannot be found
*/
**/
Q_PROPERTY(QString colorScheme READ colorScheme NOTIFY colorSchemeChanged)
public:
......@@ -418,7 +418,7 @@ public:
* (normal=window which has a border, can be moved by the user, can be closed, etc.)
* true for Desktop, Dock, Splash, Override and TopMenu (and Toolbar??? - for now)
* false for Normal, Dialog, Utility and Menu (and Toolbar??? - not yet) TODO
*/
**/
bool isSpecialWindow() const;
void sendToScreen(int screen);
const QKeySequence &shortcut() const {
......@@ -434,7 +434,7 @@ public:
/**
* Set the window as being on the attached list of desktops
* On X11 it will be set to the last entry
*/
**/
void setDesktops(QVector<VirtualDesktop *> desktops);
int desktop() const override {
......@@ -447,8 +447,8 @@ public:
void setMinimized(bool set);
/**
* Minimizes this client plus its transients
*/
* Minimizes this client plus its transients
**/
void minimize(bool avoid_animation = false);
void unminimize(bool avoid_animation = false);
bool isMinimized() const {
......@@ -470,41 +470,53 @@ public:
* all clients in this tabGroup will have property("kwin_tiling_floats").toBool() == true
*
* WARNING: non dynamic properties are ignored - you're not supposed to alter/update such explicitly
*/
**/
Q_INVOKABLE void syncTabGroupFor(QString property, bool fromThisClient = false);
TabGroup *tabGroup() const;
/**
* Set tab group - this is to be invoked by TabGroup::add/remove(client) and NO ONE ELSE
*/
**/
void setTabGroup(TabGroup* group);
virtual void setClientShown(bool shown);
Q_INVOKABLE bool untab(const QRect &toGeometry = QRect(), bool clientRemoved = false);
/*
* When a click is done in the decoration and it calls the group
* to change the visible client it starts to move-resize the new
* client, this function stops it.
*/
/**
* When a click is done in the decoration and it calls the group
* to change the visible client it starts to move-resize the new
* client, this function stops it.
**/
bool isCurrentTab() const;
virtual QRect geometryRestore() const = 0;
/**
* The currently applied maximize mode
*/
**/
virtual MaximizeMode maximizeMode() const = 0;
/**
* The maximise mode requested by the server.
* For X this always matches maximizeMode, for wayland clients it
* is asyncronous
*/
**/
virtual MaximizeMode requestedMaximizeMode() const;
void maximize(MaximizeMode);
/**
* Sets the maximization according to @p vertically and @p horizontally.
**/
void setMaximize(bool vertically, bool horizontally);
virtual bool noBorder() const = 0;
virtual void setNoBorder(bool set) = 0;
virtual void blockActivityUpdates(bool b = true) = 0;
QPalette palette() const;
const Decoration::DecorationPalette *decorationPalette() const;
/**
* Returns whether the window is resizable or has a fixed size.
**/
virtual bool isResizable() const = 0;
/**
* Returns whether the window is moveable or has a fixed position.
**/
virtual bool isMovable() const = 0;
/**
* Returns whether the window can be moved to another screen.
**/
virtual bool isMovableAcrossScreens() const = 0;
/**
* @c true only for @c ShadeNormal
......@@ -525,6 +537,9 @@ public:
* Whether the Client can be shaded. Default implementation returns @c false.
**/
virtual bool isShadeable() const;
/**
* Returns whether the window is maximizable or not.
**/
virtual bool isMaximizable() const = 0;
virtual bool isMinimizable() const = 0;
virtual QRect iconGeometry() const;
......@@ -574,7 +589,7 @@ public:
/**
* These values represent positions inside an area
*/
**/
enum Position {
// without prefix, they'd conflict with Qt::TopLeftCorner etc. :(
PositionCenter = 0x00,
......@@ -593,11 +608,12 @@ public:
// a helper for the workspace window packing. tests for screen validity and updates since in maximization case as with normal moving
void packTo(int left, int top);
/** Set the quick tile mode ("snap") of this window.
/**
* Sets the quick tile mode ("snap") of this window.
* This will also handle preserving and restoring of window geometry as necessary.
* @param mode The tile mode (left/right) to give this window.
* @param keyboard Defines whether to take keyboard cursor into account.
*/
**/
void setQuickTileMode(QuickTileMode mode, bool keyboard = false);
QuickTileMode quickTileMode() const {
return QuickTileMode(m_quickTileMode);
......@@ -623,14 +639,17 @@ public:
SizemodeMax ///< Try not to make it larger in either direction
};
/**
*Calculate the appropriate frame size for the given client size @p wsize.
* Calculates the appropriate frame size for the given client size @p wsize.
*
* @p wsize is adapted according to the window's size hints (minimum, maximum and incremental size changes).
*
* Default implementation returns the passed in @p wsize.
*/
**/
virtual QSize sizeForClientSize(const QSize &wsize, Sizemode mode = SizemodeAny, bool noframe = false) const;
/**
* Adjust the frame size @p frame according to the window's size hints.
**/
QSize adjustedSize(const QSize&, Sizemode mode = SizemodeAny) const;
QSize adjustedSize() const;
......@@ -687,23 +706,23 @@ public:
virtual void updateDecoration(bool check_workspace_pos, bool force = false) = 0;
/**
* Returns whether the window provides context help or not. If it does,
* you should show a help menu item or a help button like '?' and call
* contextHelp() if this is invoked.
*
* Default implementation returns @c false.
* @see showContextHelp;
*/
* Returns whether the window provides context help or not. If it does,
* you should show a help menu item or a help button like '?' and call
* contextHelp() if this is invoked.
*
* Default implementation returns @c false.
* @see showContextHelp;
**/
virtual bool providesContextHelp() const;
/**
* Invokes context help on the window. Only works if the window
* actually provides context help.
*
* Default implementation does nothing.
*
* @see providesContextHelp()
*/
* Invokes context help on the window. Only works if the window
* actually provides context help.
*
* Default implementation does nothing.
*
* @see providesContextHelp()
**/
virtual void showContextHelp();
QRect inputGeometry() const override;
......@@ -752,7 +771,7 @@ public:
/**
* Request showing the application menu bar
* @param actionId The DBus menu ID of the action that should be highlighted, 0 for the root menu
*/
**/
void showApplicationMenu(int actionId);
bool unresponsive() const;
......@@ -1038,8 +1057,8 @@ protected:
}
void checkUnrestrictedMoveResize();
/**
* Sets an appropriate cursor shape for the logical mouse position.
*/
* Sets an appropriate cursor shape for the logical mouse position.
**/
void updateCursor();
void startDelayedMoveResize();
void stopDelayedMoveResize();
......@@ -1073,7 +1092,7 @@ protected:
/*
* Checks if the mouse cursor is near the edge of the screen and if so
* activates quick tiling or maximization
*/
**/
void checkQuickTilingMaximizationZones(int xroot, int yroot);
/**
* Whether a sync request is still pending.
......@@ -1172,8 +1191,7 @@ private:
// electric border/quick tiling
QuickTileMode m_electricMode = QuickTileFlag::None;
bool m_electricMaximizing = false;
/** The quick tile mode of this window.
*/
// The quick tile mode of this window.
int m_quickTileMode = int(QuickTileFlag::None);
QTimer *m_electricMaximizingDelay = nullptr;
......@@ -1221,7 +1239,7 @@ private:
/**
* Helper for AbstractClient::blockGeometryUpdates() being called in pairs (true/false)
*/
**/
class GeometryUpdatesBlocker
{
public:
......
......@@ -71,18 +71,18 @@ public:
qreal scale() const {
return m_scale;
}
/*
/**
* The geometry of this output in global compositor co-ordinates (i.e scaled)
*/
**/
QRect geometry() const;
QSize physicalSize() const;
Qt::ScreenOrientation orientation() const {
return m_orientation;
}
/*
* Current refresh rate in 1/ms
*/
/**
* Current refresh rate in 1/ms.
**/
int refreshRate() const;
bool isInternal() const {
......@@ -93,8 +93,8 @@ public:
void setScale(qreal scale);
/**
* This sets the changes and tests them against the specific output
*/
* This sets the changes and tests them against the specific output.
**/
void setChanges(KWayland::Server::OutputChangeSet *changeset);
QPointer<KWayland::Server::OutputInterface> waylandOutput() const {
......@@ -103,10 +103,10 @@ public:
/**
* Enable or disable the output.
* This differs from updateDpms as it also
* removes the wl_output.
*
* This differs from updateDpms as it also removes the wl_output.
* The default is on.
*/
**/
void setEnabled(bool enable);
virtual int getGammaRampSize() const {
......
......@@ -219,14 +219,14 @@ namespace KWin
//****************************************
/*!
Informs the workspace about the active client, i.e. the client that
has the focus (or None if no client has the focus). This functions
is called by the client itself that gets focus. It has no other
effect than fixing the focus chain and the return value of
activeClient(). And of course, to propagate the active client to the
world.
*/
/**
* Informs the workspace about the active client, i.e. the client that
* has the focus (or None if no client has the focus). This functions
* is called by the client itself that gets focus. It has no other
* 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)
......@@ -278,17 +278,18 @@ void Workspace::setActiveClient(AbstractClient* c)
--set_active_client_recursion;
}
/*!
Tries to activate the client \a c. This function performs what you
expect when clicking the respective entry in a taskbar: showing and
raising the client (this may imply switching to the another virtual
desktop) and putting the focus onto it. Once X really gave focus to
the client window as requested, the client itself will call
setActiveClient() and the operation is complete. This may not happen
with certain focus policies, though.
\sa stActiveClient(), requestFocus()
*/
/**
* Tries to activate the client \a c. This function performs what you
* expect when clicking the respective entry in a taskbar: showing and
* raising the client (this may imply switching to the another virtual
* desktop) and putting the focus onto it. Once X really gave focus to
* the client window as requested, the client itself will call
* setActiveClient() and the operation is complete. This may not happen
* with certain focus policies, though.
*
* @see setActiveClient
* @see requestFocus
**/
void Workspace::activateClient(AbstractClient* c, bool force)
{
if (c == NULL) {
......@@ -333,13 +334,13 @@ void Workspace::activateClient(AbstractClient* c, bool force)
}
}
/*!
Tries to activate the client by asking X for the input focus. This
function does not perform any show, raise or desktop switching. See
Workspace::activateClient() instead.
\sa Workspace::activateClient()
*/
/**
* Tries to activate the client by asking X for the input focus. This
* function does not perform any show, raise or desktop switching. See
* Workspace::activateClient() instead.
*
* @see activateClient
**/
void Workspace::requestFocus(AbstractClient* c, bool force)
{
takeActivity(c, force ? ActivityFocusForce : ActivityFocus);
......@@ -404,13 +405,13 @@ void Workspace::takeActivity(AbstractClient* c, ActivityFlags flags)
screens()->setCurrent(c->screen());
}
/*!
Informs the workspace that the client \a c has been hidden. If it
was the active client (or to-become the active client),
the workspace activates another one.
\a c may already be destroyed
*/
/**
* Informs the workspace that the client \a c has been hidden. If it
* was the active client (or to-become the active client),
* 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());
......@@ -700,12 +701,12 @@ void Workspace::clientAttentionChanged(AbstractClient* c, bool set)
// Client
//********************************************
/*!
Updates the user time (time of last action in the active window).
This is called inside kwin for every action with the window
that qualifies for user interaction (clicking on it, activate it
externally, etc.).
*/
/**
* Updates the user time (time of last action in the active window).
* 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
......
......@@ -46,10 +46,10 @@ public:
bool start(const QString &id);
void setCurrent(const QString &activity);
/**
* Adds/removes client \a c to/from \a activity.
*
* Takes care of transients as well.
*/
* 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:
......
......@@ -86,12 +86,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()
......@@ -184,7 +184,7 @@ Client::Client()
/**
* "Dumb" destructor.
*/
**/
Client::~Client()
{
if (m_killHelperPID && !::kill(m_killHelperPID, 0)) { // means the process is alive
......@@ -212,7 +212,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);
......@@ -282,7 +282,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);
......@@ -567,7 +567,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();
......@@ -690,7 +690,7 @@ void Client::hideClient(bool hide)
/**
* Returns whether the window is minimizable or not
*/
**/
bool Client::isMinimizable() const
{
if (isSpecialWindow() && !isTransient())
......@@ -930,7 +930,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);
......@@ -998,7 +998,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
......@@ -1019,7 +1019,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
......@@ -1047,7 +1047,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()) {
......@@ -1085,7 +1085,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());
......@@ -1093,7 +1093,7 @@ bool Client::isCloseable() const
/**
* Closes the window by either sending a delete_window message or using XKill.
*/
**/
void Client::closeWindow()
{
if (!isCloseable())
......@@ -1113,7 +1113,7 @@ void Client::closeWindow()
/**
* Kills the window via XKill
*/
**/
void Client::killWindow()
{
qCDebug(KWIN_CORE) << "Client::killWindow():" << caption();
......@@ -1125,7 +1125,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))
......@@ -1237,7 +1237,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
......@@ -1263,7 +1263,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
......@@ -1320,7 +1320,7 @@ void Client::blockActivityUpdates(bool b)
/**
* update after activities changed
*/
**/
void Client::updateActivities(bool includeTransients)
{
if (m_activityUpdatesBlocked) {
......@@ -1342,7 +1342,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) {
......@@ -1354,7 +1354,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
......@@ -1373,7 +1373,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()))
......@@ -1404,7 +1404,7 @@ void Client::takeFocus()
* contextHelp() if this is invoked.
*
* \sa contextHelp()
*/
**/
bool Client::providesContextHelp() const
{
return info->supportsProtocol(NET::ContextHelpProtocol);
......@@ -1415,7 +1415,7 @@ bool Client::providesContextHelp() const
* actually provides context help.
*
* \sa providesContextHelp()
*/
**/
void Client::showContextHelp()
{
if (info->supportsProtocol(NET::ContextHelpProtocol)) {
......@@ -1426,7 +1426,7 @@ void Client::showContextHelp()
/**
* Fetches the window's caption (WM_NAME property). It will be
* stored in the client's caption().
*/