From e9cacbd92daf19c92f083037f6e0ef70dc687218 Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Sun, 14 Jul 2024 16:17:51 -0700 Subject: [PATCH] all: use type/prop shorthand in docs --- src/core/desktopentry.hpp | 4 ++-- src/core/lazyloader.hpp | 2 +- src/core/objectrepeater.hpp | 10 +++------- src/core/qmlscreen.hpp | 7 ++----- src/core/qsmenu.hpp | 2 +- src/core/reload.hpp | 5 +---- src/core/retainable.hpp | 8 ++++---- src/core/variants.hpp | 7 ++----- src/io/datastream.hpp | 4 ++-- src/services/notifications/notification.hpp | 16 ++++++---------- src/services/notifications/qml.hpp | 10 ++++------ src/services/pipewire/qml.hpp | 2 +- src/services/status_notifier/qml.hpp | 4 ++-- src/wayland/session_lock.hpp | 11 +++-------- src/wayland/toplevel_management/qml.hpp | 4 ++-- src/wayland/wlr_layershell.hpp | 3 +-- src/wayland/wlr_layershell/window.hpp | 2 +- 17 files changed, 38 insertions(+), 63 deletions(-) diff --git a/src/core/desktopentry.hpp b/src/core/desktopentry.hpp index 81cfa8f0..e227eb19 100644 --- a/src/core/desktopentry.hpp +++ b/src/core/desktopentry.hpp @@ -13,7 +13,7 @@ class DesktopAction; -/// A desktop entry. See [DesktopEntries](../desktopentries) for details. +/// A desktop entry. See @@DesktopEntries for details. class DesktopEntry: public QObject { Q_OBJECT; Q_PROPERTY(QString id MEMBER mId CONSTANT); @@ -75,7 +75,7 @@ private: friend class DesktopAction; }; -/// An action of a [DesktopEntry](../desktopentry). +/// An action of a @@DesktopEntry$. class DesktopAction: public QObject { Q_OBJECT; Q_PROPERTY(QString id MEMBER mId CONSTANT); diff --git a/src/core/lazyloader.hpp b/src/core/lazyloader.hpp index 8ef935f6..34bd2a70 100644 --- a/src/core/lazyloader.hpp +++ b/src/core/lazyloader.hpp @@ -79,7 +79,7 @@ /// > [!WARNING] Components that internally load other components must explicitly /// > support asynchronous loading to avoid blocking. /// > -/// > Notably, [Variants](../variants) does not corrently support asynchronous +/// > Notably, @@Variants does not corrently support asynchronous /// > loading, meaning using it inside a LazyLoader will block similarly to not /// > having a loader to start with. /// diff --git a/src/core/objectrepeater.hpp b/src/core/objectrepeater.hpp index 0361636f..2350971c 100644 --- a/src/core/objectrepeater.hpp +++ b/src/core/objectrepeater.hpp @@ -14,9 +14,7 @@ /// > [!ERROR] Removed in favor of QtQml.Models.Instantiator /// /// The ObjectRepeater creates instances of the provided delegate for every entry in the -/// given model, similarly to a [Repeater] but for non visual types. -/// -/// [Repeater]: https://doc.qt.io/qt-6/qml-qtquick-repeater.html +/// given model, similarly to a @@QtQuick.Repeater but for non visual types. class ObjectRepeater: public ObjectModel { Q_OBJECT; /// The model providing data to the ObjectRepeater. @@ -25,10 +23,9 @@ class ObjectRepeater: public ObjectModel { /// and [QAbstractListModel] derived models, though only one column will be repeated /// from the latter. /// - /// Note: [ObjectModel] is a [QAbstractListModel] with a single column. + /// Note: @@ObjectModel is a [QAbstractListModel] with a single column. /// /// [QAbstractListModel]: https://doc.qt.io/qt-6/qabstractlistmodel.html - /// [ObjectModel]: ../objectmodel Q_PROPERTY(QVariant model READ model WRITE setModel NOTIFY modelChanged); /// The delegate component to repeat. /// @@ -39,10 +36,9 @@ class ObjectRepeater: public ObjectModel { /// exposed containing the entry from the model. If the model is a [QAbstractListModel], /// the roles from the model will be exposed. /// - /// Note: [ObjectModel] has a single role named `modelData` for compatibility with normal lists. + /// Note: @@ObjectModel has a single role named `modelData` for compatibility with normal lists. /// /// [QAbstractListModel]: https://doc.qt.io/qt-6/qabstractlistmodel.html - /// [ObjectModel]: ../objectmodel Q_PROPERTY(QQmlComponent* delegate READ delegate WRITE setDelegate NOTIFY delegateChanged); Q_CLASSINFO("DefaultProperty", "delegate"); QML_ELEMENT; diff --git a/src/core/qmlscreen.hpp b/src/core/qmlscreen.hpp index dfebf331..69c0762d 100644 --- a/src/core/qmlscreen.hpp +++ b/src/core/qmlscreen.hpp @@ -12,17 +12,14 @@ // unfortunately QQuickScreenInfo is private. -/// Monitor object useful for setting the monitor for a [ShellWindow] +/// Monitor object useful for setting the monitor for a @@QsWindow /// or querying information about the monitor. /// /// > [!WARNING] If the monitor is disconnected than any stored copies of its ShellMonitor will /// > be marked as dangling and all properties will return default values. /// > Reconnecting the monitor will not reconnect it to the ShellMonitor object. /// -/// Due to some technical limitations, it was not possible to reuse the native qml [Screen] type. -/// -/// [ShellWindow]: ../shellwindow -/// [Screen]: https://doc.qt.io/qt-6/qml-qtquick-screen.html +/// Due to some technical limitations, it was not possible to reuse the native qml @@QtQuick.Screen type. class QuickshellScreenInfo: public QObject { Q_OBJECT; QML_NAMED_ELEMENT(ShellScreen); diff --git a/src/core/qsmenu.hpp b/src/core/qsmenu.hpp index a5f38225..2d2413a4 100644 --- a/src/core/qsmenu.hpp +++ b/src/core/qsmenu.hpp @@ -60,7 +60,7 @@ class QsMenuEntry: public QObject { /// The check state of the checkbox or radiobutton if applicable, as a /// [Qt.CheckState](https://doc.qt.io/qt-6/qt.html#CheckState-enum). Q_PROPERTY(Qt::CheckState checkState READ checkState NOTIFY checkStateChanged); - /// If this menu item has children that can be accessed through a [QsMenuOpener](../qsmenuopener). + /// If this menu item has children that can be accessed through a @@QsMenuOpener$. Q_PROPERTY(bool hasChildren READ hasChildren NOTIFY hasChildrenChanged); QML_ELEMENT; QML_UNCREATABLE("QsMenuEntry cannot be directly created"); diff --git a/src/core/reload.hpp b/src/core/reload.hpp index 0d33e2b6..36956f5a 100644 --- a/src/core/reload.hpp +++ b/src/core/reload.hpp @@ -11,10 +11,7 @@ class EngineGeneration; ///! The base class of all types that can be reloaded. /// Reloadables will attempt to take specific state from previous config revisions if possible. -/// Some examples are [ProxyWindowBase] and [PersistentProperties] -/// -/// [ProxyWindowBase]: ../proxywindowbase -/// [PersistentProperties]: ../persistentproperties +/// Some examples are @@ProxyWindowBase and @@PersistentProperties class Reloadable : public QObject , public QQmlParserStatus { diff --git a/src/core/retainable.hpp b/src/core/retainable.hpp index 598d6f95..5ef02f80 100644 --- a/src/core/retainable.hpp +++ b/src/core/retainable.hpp @@ -17,7 +17,7 @@ class Retainable; /// typeinfo pages. /// /// > [!INFO] Working directly with Retainable is often overly complicated and -/// > error prone. For this reason [RetainableLock](../retainablelock) should +/// > error prone. For this reason @@RetainableLock should /// > usually be used instead. class RetainableHook: public QObject { Q_OBJECT; @@ -43,7 +43,7 @@ public: /// > [!WARNING] It is easy to forget to unlock a locked object. /// > Doing so will create what is effectively a memory leak. /// > - /// > Using [RetainableLock](../retainablelock) is recommended as it will help + /// > Using @@RetainableLock is recommended as it will help /// > avoid this scenario and make misuse more obvious. Q_INVOKABLE void lock(); /// Remove a lock on the object. See `lock()` for more information. @@ -105,8 +105,8 @@ private: ///! A helper for easily using Retainable. /// A RetainableLock provides extra safety and ease of use for locking -/// [Retainable](../retainable) objects. A retainable object can be locked -/// by multiple locks at once, and each lock re-exposes relevant properties +/// @@Retainable objects. A retainable object can be locked by multiple +/// locks at once, and each lock re-exposes relevant properties /// of the retained objects. /// /// #### Example diff --git a/src/core/variants.hpp b/src/core/variants.hpp index a9071cf8..f0f3c6f1 100644 --- a/src/core/variants.hpp +++ b/src/core/variants.hpp @@ -28,20 +28,17 @@ public: ///! Creates instances of a component based on a given model. /// Creates and destroys instances of the given component when the given property changes. /// -/// `Variants` is similar to [Repeater] except it is for *non Item* objects, and acts as +/// `Variants` is similar to @@QtQuick.Repeater except it is for *non Item* objects, and acts as /// a reload scope. /// /// Each non duplicate value passed to [model](#prop.model) will create a new instance of /// [delegate](#prop.delegate) with its `modelData` property set to that value. /// -/// See [Quickshell.screens] for an example of using `Variants` to create copies of a window per +/// See @@Quickshell.screens for an example of using `Variants` to create copies of a window per /// screen. /// /// > [!WARNING] BUG: Variants currently fails to reload children if the variant set is changed as /// > it is instantiated. (usually due to a mutation during variant creation) -/// -/// [Repeater]: https://doc.qt.io/qt-6/qml-qtquick-repeater.html -/// [Quickshell.screens]: ../quickshell#prop.screens class Variants: public Reloadable { Q_OBJECT; /// The component to create instances of. diff --git a/src/io/datastream.hpp b/src/io/datastream.hpp index 24aa54a4..76a25f2b 100644 --- a/src/io/datastream.hpp +++ b/src/io/datastream.hpp @@ -10,7 +10,7 @@ class DataStreamParser; ///! Data source that can be streamed into a parser. -/// See also: [DataStreamParser](../datastreamparser) +/// See also: @@DataStreamParser class DataStream: public QObject { Q_OBJECT; /// The parser to stream data from this source into. @@ -43,7 +43,7 @@ protected: }; ///! Parser for streamed input data. -/// See also: [DataStream](../datastream), [SplitParser](../splitparser) +/// See also: @@DataStream$, @@SplitParser class DataStreamParser: public QObject { Q_OBJECT; QML_ELEMENT; diff --git a/src/services/notifications/notification.hpp b/src/services/notifications/notification.hpp index 2dab36dc..4f34f7b6 100644 --- a/src/services/notifications/notification.hpp +++ b/src/services/notifications/notification.hpp @@ -53,7 +53,7 @@ class NotificationAction; ///! A notification emitted by a NotificationServer. /// A notification emitted by a NotificationServer. -/// > [!INFO] This type is [Retainable](/docs/types/quickshell/retainable). It +/// > [!INFO] This type is @@Quickshell.Retainable$. It /// > can be retained after destruction if necessary. class Notification : public QObject @@ -68,8 +68,8 @@ class Notification /// If this notification was carried over from the last generation /// when quickshell reloaded. /// - /// Notifications from the last generation will only be emitted if - /// [NotificationServer.keepOnReload](../notificationserver#prop.keepOnReload) is true. + /// Notifications from the last generation will only be emitted + /// if @@NotificationServer.keepOnReloadis true. Q_PROPERTY(bool lastGeneration READ isLastGeneration CONSTANT); /// Time in seconds the notification should be valid for Q_PROPERTY(qreal expireTimeout READ expireTimeout NOTIFY expireTimeoutChanged); @@ -86,7 +86,7 @@ class Notification Q_PROPERTY(QVector actions READ actions NOTIFY actionsChanged); /// If actions associated with this notification have icons available. /// - /// See [NotificationAction.identifier](../notificationaction#prop.identifier) for details. + /// See @@NotificationAction.identifier for details. Q_PROPERTY(bool hasActionIcons READ hasActionIcons NOTIFY hasActionIconsChanged); /// If true, the notification will not be destroyed after an action is invoked. Q_PROPERTY(bool resident READ isResident NOTIFY isResidentChanged); @@ -194,10 +194,8 @@ class NotificationAction: public QObject { Q_OBJECT; /// The identifier of the action. /// - /// When [Notification.hasActionIcons] is true, this property will be an icon name. + /// When @@Notification.hasActionIcons is true, this property will be an icon name. /// When it is false, this property is irrelevant. - /// - /// [Notification.hasActionIcons]: ../notification#prop.hasActionIcons Q_PROPERTY(QString identifier READ identifier CONSTANT); /// The localized text that should be displayed on a button. Q_PROPERTY(QString text READ text NOTIFY textChanged); @@ -211,9 +209,7 @@ public: , mIdentifier(std::move(identifier)) , mText(std::move(text)) {} - /// Invoke the action. If [Notification.resident] is false it will be dismissed. - /// - /// [Notification.resident]: ../notification#prop.resident + /// Invoke the action. If @@Notification.resident is false it will be dismissed. Q_INVOKABLE void invoke(); [[nodiscard]] QString identifier() const; diff --git a/src/services/notifications/qml.hpp b/src/services/notifications/qml.hpp index 341eaf2a..86851030 100644 --- a/src/services/notifications/qml.hpp +++ b/src/services/notifications/qml.hpp @@ -27,7 +27,7 @@ class NotificationServerQml // clang-format off /// If notifications should be re-emitted when quickshell reloads. Defaults to true. /// - /// The [lastGeneration](../notification#prop.lastGeneration) flag will be + /// The @@Notification.lastGeneration flag will be /// set on notifications from the prior generation for further filtering/handling. Q_PROPERTY(bool keepOnReload READ keepOnReload WRITE setKeepOnReload NOTIFY keepOnReloadChanged); /// If the notification server should advertise that it can persist notifications in the background @@ -42,11 +42,9 @@ class NotificationServerQml /// If notification body text should be advertised as supporting markup as described in [the specification] /// Defaults to false. /// - /// Note that returned notifications may still contain markup if this property is false, as it is only a hint. - /// By default Text objects will try to render markup. To avoid this if any is sent, change [Text.textFormat] to `PlainText`. - /// - /// [the specification]: https://specifications.freedesktop.org/notification-spec/notification-spec-latest.html#markup - /// [Text.textFormat]: https://doc.qt.io/qt-6/qml-qtquick-text.html#textFormat-prop + /// Note that returned notifications may still contain markup if this property is false, + /// as it is only a hint. By default Text objects will try to render markup. To avoid this + /// if any is sent, change @@QtQuick.Text.textFormat to `PlainText`. Q_PROPERTY(bool bodyMarkupSupported READ bodyMarkupSupported WRITE setBodyMarkupSupported NOTIFY bodyMarkupSupportedChanged); /// If notification body text should be advertised as supporting hyperlinks as described in [the specification] /// Defaults to false. diff --git a/src/services/pipewire/qml.hpp b/src/services/pipewire/qml.hpp index 78e75633..708b7282 100644 --- a/src/services/pipewire/qml.hpp +++ b/src/services/pipewire/qml.hpp @@ -249,7 +249,7 @@ private: ///! A connection between pipewire nodes. /// Note that there is one link per *channel* of a connection between nodes. -/// You usually want [PwLinkGroup](../pwlinkgroup). +/// You usually want @@PwLinkGroup$. class PwLinkIface: public PwObjectIface { Q_OBJECT; /// The pipewire object id of the link. diff --git a/src/services/status_notifier/qml.hpp b/src/services/status_notifier/qml.hpp index 9510285a..7c89055a 100644 --- a/src/services/status_notifier/qml.hpp +++ b/src/services/status_notifier/qml.hpp @@ -61,7 +61,7 @@ class SystemTrayItem: public QObject { Q_PROPERTY(QString tooltipTitle READ tooltipTitle NOTIFY tooltipTitleChanged); Q_PROPERTY(QString tooltipDescription READ tooltipDescription NOTIFY tooltipDescriptionChanged); /// If this tray item has an associated menu accessible via `display` - /// or a [SystemTrayMenuWatcher](../systemtraymenuwatcher). + /// or a @@SystemTrayMenuWatcher$. Q_PROPERTY(bool hasMenu READ hasMenu NOTIFY hasMenuChanged); /// If this tray item only offers a menu and activation will do nothing. Q_PROPERTY(bool onlyMenu READ onlyMenu NOTIFY onlyMenuChanged); @@ -133,7 +133,7 @@ private: ///! Accessor for SystemTrayItem menus. /// SystemTrayMenuWatcher provides access to the associated -/// [DBusMenuItem](../../quickshell.dbusmenu/dbusmenuitem) for a tray item. +/// @@Quickshell.DBusMenu.DBusMenuItem for a tray item. class SystemTrayMenuWatcher: public QObject { using DBusMenu = qs::dbus::dbusmenu::DBusMenu; using DBusMenuItem = qs::dbus::dbusmenu::DBusMenuItem; diff --git a/src/wayland/session_lock.hpp b/src/wayland/session_lock.hpp index a44dae0c..9a34eafa 100644 --- a/src/wayland/session_lock.hpp +++ b/src/wayland/session_lock.hpp @@ -25,7 +25,7 @@ class WlSessionLockSurface; /// Wayland session lock implemented using the [ext_session_lock_v1] protocol. /// /// WlSessionLock will create an instance of its `surface` component for every screen when -/// `locked` is set to true. The `surface` component must create a [WlSessionLockSurface] +/// `locked` is set to true. The `surface` component must create a @@WlSessionLockSurface /// which will be displayed on each screen. /// /// The below example will create a session lock that disappears when the button is clicked. @@ -53,7 +53,6 @@ class WlSessionLockSurface; /// > but it will render it inoperable. /// /// [ext_session_lock_v1]: https://wayland.app/protocols/ext-session-lock-v1 -/// [WlSessionLockSurface]: ../wlsessionlocksurface class WlSessionLock: public Reloadable { Q_OBJECT; // clang-format off @@ -66,9 +65,7 @@ class WlSessionLock: public Reloadable { /// /// This is set to true once the compositor has confirmed all screens are covered with locks. Q_PROPERTY(bool secure READ isSecure NOTIFY secureStateChanged); - /// The surface that will be created for each screen. Must create a [WlSessionLockSurface]. - /// - /// [WlSessionLockSurface]: ../wlsessionlocksurface + /// The surface that will be created for each screen. Must create a @@WlSessionLockSurface$. Q_PROPERTY(QQmlComponent* surface READ surfaceComponent WRITE setSurfaceComponent NOTIFY surfaceComponentChanged); // clang-format on QML_ELEMENT; @@ -109,9 +106,7 @@ private: }; ///! Surface to display with a `WlSessionLock`. -/// Surface displayed by a [WlSessionLock] when it is locked. -/// -/// [WlSessionLock]: ../wlsessionlock +/// Surface displayed by a @@WlSessionLock when it is locked. class WlSessionLockSurface: public Reloadable { Q_OBJECT; // clang-format off diff --git a/src/wayland/toplevel_management/qml.hpp b/src/wayland/toplevel_management/qml.hpp index 8bb1d551..19d64dfa 100644 --- a/src/wayland/toplevel_management/qml.hpp +++ b/src/wayland/toplevel_management/qml.hpp @@ -17,7 +17,7 @@ class ToplevelHandle; ///! Window from another application. /// A window/toplevel from another application, retrievable from -/// the [ToplevelManager](../toplevelmanager). +/// the @@ToplevelManager$. class Toplevel: public QObject { Q_OBJECT; Q_PROPERTY(QString appId READ appId NOTIFY appIdChanged); @@ -122,7 +122,7 @@ private: }; ///! Exposes a list of Toplevels. -/// Exposes a list of windows from other applications as [Toplevel](../toplevel)s via the +/// Exposes a list of windows from other applications as @@Toplevel$s via the /// [zwlr-foreign-toplevel-management-v1](https://wayland.app/protocols/wlr-foreign-toplevel-management-unstable-v1) /// wayland protocol. class ToplevelManagerQml: public QObject { diff --git a/src/wayland/wlr_layershell.hpp b/src/wayland/wlr_layershell.hpp index cf9abe4f..b289bbe4 100644 --- a/src/wayland/wlr_layershell.hpp +++ b/src/wayland/wlr_layershell.hpp @@ -16,7 +16,7 @@ /// Decorationless window that can be attached to the screen edges using the [zwlr_layer_shell_v1] protocol. /// /// #### Attached property -/// `WlrLayershell` works as an attached property of [PanelWindow] which you should use instead if you can, +/// `WlrLayershell` works as an attached property of @@Quickshell.PanelWindow which you should use instead if you can, /// as it is platform independent. /// ```qml /// PanelWindow { @@ -37,7 +37,6 @@ /// ``` /// /// [zwlr_layer_shell_v1]: https://wayland.app/protocols/wlr-layer-shell-unstable-v1 -/// [PanelWindow]: ../../quickshell/panelwindow class WlrLayershell: public ProxyWindowBase { QSDOC_BASECLASS(PanelWindowInterface); // clang-format off diff --git a/src/wayland/wlr_layershell/window.hpp b/src/wayland/wlr_layershell/window.hpp index 8ce08b5c..b73e8a78 100644 --- a/src/wayland/wlr_layershell/window.hpp +++ b/src/wayland/wlr_layershell/window.hpp @@ -41,7 +41,7 @@ enum Enum { /// /// > [!WARNING] You **CANNOT** use this to make a secure lock screen. /// > - /// > If you want to make a lock screen, use [WlSessionLock](../wlsessionlock). + /// > If you want to make a lock screen, use @@WlSessionLock$. Exclusive = 1, /// Access to the keyboard as determined by the operating system. ///