docs: Review RcDocument API

Add missing properties and small doc improvement. Related-to #54
KDAB · Jul 16, 2024 · a2f97fb · a2f97fb
1 parent 7c1a04e
commit a2f97fb
Show file tree

Hide file tree

Showing 6 changed files with 53 additions and 17 deletions.
diff --git a/docs/API/knut/action.md b/docs/API/knut/action.md
@@ -11,10 +11,12 @@ import Knut
 | | Name |
 |-|-|
 |bool|**[checked](#checked)**|
+|string|**[iconId](#iconId)**|
 |string|**[iconPath](#iconPath)**|
 |string|**[id](#id)**|
 |array&lt;[Shortcut](../knut/shortcut.md)>|**[shortcuts](#shortcuts)**|
 |string|**[statusTip](#statusTip)**|
+|string|**[title](#title)**|
 |string|**[toolTip](#toolTip)**|
 
 ## Property Documentation
@@ -23,6 +25,10 @@ import Knut
 
 This property is `true` if the action is checkabled and checked by default.
 
+#### <a name="iconId"></a>string **iconId**
+
+This property holds the id of the icon, if any.
+
 #### <a name="iconPath"></a>string **iconPath**
 
 This property holds the fileName for the icon of the action.
@@ -39,6 +45,10 @@ This property holds all the shortcuts associated with the action.
 
 This property holds the statusTip of the action.
 
+#### <a name="title"></a>string **title**
+
+This property holds the title of the action.
+
 #### <a name="toolTip"></a>string **toolTip**
 
 This property holds the toolTip of the action.
diff --git a/docs/API/knut/rcdocument.md b/docs/API/knut/rcdocument.md
@@ -18,6 +18,7 @@ import Knut
 |array&lt;string>|**[languages](#languages)**|
 |array&lt;string>|**[menuIds](#menuIds)**|
 |array&lt;[Menu](../knut/menu.md)>|**[menus](#menus)**|
+|array&lt;string>|**[ribbonIds](#ribbonIds)**|
 |array&lt;string>|**[stringIds](#stringIds)**|
 |array&lt;string>|**[strings](#strings)**|
 |array&lt;string>|**[toolbarIds](#toolbarIds)**|
@@ -40,11 +41,11 @@ import Knut
 |bool |**[mergeLanguages](#mergeLanguages)**()|
 |bool |**[previewDialog](#previewDialog)**([Widget](../knut/widget.md) dialog)|
 |[Menu](../knut/menu.md) |**[ribbon](#ribbon)**(string id)|
+|string |**[string](#string)**(string id)|
 |string |**[stringForDialog](#stringForDialog)**(string dialogId, string id)|
 |string |**[stringForDialogAndLanguage](#stringForDialogAndLanguage)**(string language, string dialogId, string id)|
 |string |**[stringForLanguage](#stringForLanguage)**(string language, string id)|
 |array&lt;[String](../knut/string.md)> |**[stringsForLanguage](#stringsForLanguage)**(string language)|
-|string |**[text](#text)**(string id)|
 |[ToolBar](../knut/toolbar.md) |**[toolBar](#toolBar)**(string id)|
 |bool |**[writeAssetsToImage](#writeAssetsToImage)**(int flags)|
 |bool |**[writeAssetsToQrc](#writeAssetsToQrc)**(string fileName)|
@@ -85,6 +86,10 @@ This read-only property holds the list of menu's ids in the RC file.
 
 This read-only property holds the list of menus in the RC file.
 
+#### <a name="ribbonIds"></a>array&lt;string> **ribbonIds**
+
+This read-only property holds the list of ribbons available in the file.
+
 #### <a name="stringIds"></a>array&lt;string> **stringIds**
 
 This read-only property holds the list of string's ids in the RC file.
@@ -127,7 +132,7 @@ Returns all actions used in the toolbar `toolBarId`.
 !!! Warning "Experimental API"
     The API here is still experimental, and may change in follow-up release. Use it at your own risk.
 
-Convert all actions using the `flags`.
+Converts all actions using the `flags`.
 
 The `flags` are used to fill the iconPath of the action:
 
@@ -138,7 +143,7 @@ The `flags` are used to fill the iconPath of the action:
 
 #### <a name="convertAssets"></a>**convertAssets**(int flags)
 
-Convert all assets using the `flags`.
+Converts all assets using the `flags`.
 
 - `RcDocument.RemoveUnknown`: remove the unknown assets
 - `RcDocument.SplitToolBar`: split toolbars strip into individual icon, one per action
@@ -180,19 +185,23 @@ resulting language they will be merged together.
 
 #### <a name="previewDialog"></a>bool **previewDialog**([Widget](../knut/widget.md) dialog)
 
-Preview the result of the conversion RC->UI
+Previews the result of the conversion RC->UI
 
 #### <a name="ribbon"></a>[Menu](../knut/menu.md) **ribbon**(string id)
 
 Returns the ribbon for the given `id`.
 
+#### <a name="string"></a>string **string**(string id)
+
+Returns the string for the given `id`.
+
 #### <a name="stringForDialog"></a>string **stringForDialog**(string dialogId, string id)
 
-Return the string for the given `dialogid` and id.
+Returns the string with `id` for the given `dialogid`.
 
 #### <a name="stringForDialogAndLanguage"></a>string **stringForDialogAndLanguage**(string language, string dialogId, string id)
 
-Return the string for the given `language`, `dialogid` and id.
+Returns the string with `id` for the given `language` and `dialogid`.
 
 #### <a name="stringForLanguage"></a>string **stringForLanguage**(string language, string id)
 
@@ -202,10 +211,6 @@ Return the string for the given `id` in language `language`.
 
 Returns translated string for specific `language`.
 
-#### <a name="text"></a>string **text**(string id)
-
-Return the string for the given `id`.
-
 #### <a name="toolBar"></a>[ToolBar](../knut/toolbar.md) **toolBar**(string id)
 
 Returns the toolbar for the given `id`.

diff --git a/docs/API/knut/ribbon.md b/docs/API/knut/ribbon.md
@@ -12,6 +12,7 @@ import Knut
 |-|-|
 |array&lt;[RibbonCategory](../knut/ribboncategory.md)>|**[categories](#categories)**|
 |array&lt;[RibbonContext](../knut/ribboncontext.md)>|**[contexts](#contexts)**|
+|string|**[id](#id)**|
 |[RibbonMenu](../knut/ribbonmenu.md)|**[menu](#menu)**|
 
 ## Detailed Description
@@ -35,6 +36,10 @@ This property holds the children categories of this ribbon.
 
 This property holds the children contexts of this ribbon.
 
+#### <a name="id"></a>string **id**
+
+This property holds the id of the ribbon.
+
 #### <a name="menu"></a>[RibbonMenu](../knut/ribbonmenu.md) **menu**
 
 This property holds the menu of the ribbon.
diff --git a/src/core/rcdocument.cpp b/src/core/rcdocument.cpp
@@ -83,6 +83,10 @@ namespace Core {
  * \qmlproperty array<string> RcDocument::languages
  * This read-only property holds the list of languages available in the file.
  */
+/*!
+ * \qmlproperty array<string> RcDocument::ribbonIds
+ * This read-only property holds the list of ribbons available in the file.
+ */
 
 RcDocument::RcDocument(QObject *parent)
     : Document(Type::Rc, parent)
@@ -390,8 +394,8 @@ QList<RcCore::String> RcDocument::strings() const
 }
 
 /*!
- * \qmlmethod string RcDocument::text(string id)
- * Return the string for the given `id`.
+ * \qmlmethod string RcDocument::string(string id)
+ * Returns the string for the given `id`.
  */
 QString RcDocument::string(const QString &id) const
 {
@@ -432,7 +436,7 @@ QString extractStringForDialog(const RcCore::Data::Dialog *dialog, const QString
 
 /*!
  * \qmlmethod string RcDocument::stringForDialogAndLanguage(string language, string dialogId, string id)
- * Return the string for the given `language`, `dialogid` and id.
+ * Returns the string with `id` for the given `language` and `dialogid`.
  */
 QString RcDocument::stringForDialogAndLanguage(const QString &language, const QString &dialogId,
                                                const QString &id) const
@@ -451,7 +455,7 @@ QString RcDocument::stringForDialogAndLanguage(const QString &language, const QS
 
 /*!
  * \qmlmethod string RcDocument::stringForDialog(string dialogId, string id)
- * Return the string for the given `dialogid` and id.
+ * Returns the string with `id` for the given `dialogid`.
  */
 QString RcDocument::stringForDialog(const QString &dialogId, const QString &id) const
 {
@@ -523,7 +527,7 @@ QList<RcCore::Menu> RcDocument::menus() const
  * \sa RcDocument::writeAssetsToImage
  * \sa RcDocument::writeAssetsToQrc
  *
- * Convert all assets using the `flags`.
+ * Converts all assets using the `flags`.
  *
  * - `RcDocument.RemoveUnknown`: remove the unknown assets
  * - `RcDocument.SplitToolBar`: split toolbars strip into individual icon, one per action
@@ -544,7 +548,7 @@ void RcDocument::convertAssets(int flags)
 /*!
  * \qmlmethod void RcDocument::convertActions(int flags)
  * \todo
- * Convert all actions using the `flags`.
+ * Converts all actions using the `flags`.
  *
  * The `flags` are used to fill the iconPath of the action:
  *
@@ -632,7 +636,7 @@ bool RcDocument::writeDialogToUi(const RcCore::Widget &dialog, const QString &fi
 /*!
  * \qmlmethod bool RcDocument::previewDialog(Widget dialog )
  * \sa RcDocument::dialog
- * Preview the result of the conversion RC->UI
+ * Previews the result of the conversion RC->UI
  */
 void RcDocument::previewDialog(const RcCore::Widget &dialog) const
 {

diff --git a/src/rccore/data.cpp b/src/rccore/data.cpp
@@ -205,6 +205,14 @@ namespace RcCore {
  * \qmlproperty bool Action::checked
  * This property is `true` if the action is checkabled and checked by default.
  */
+/*!
+ * \qmlproperty string Action::title
+ * This property holds the title of the action.
+ */
+/*!
+ * \qmlproperty string Action::iconId
+ * This property holds the id of the icon, if any.
+ */
 
 /*!
  * \qmltype String

diff --git a/src/rccore/ribbon.cpp b/src/rccore/ribbon.cpp
@@ -166,6 +166,10 @@ namespace RcCore {
  * - multiple contexts, a context showing another tab with it's name in the titlebar
  *     - each context contains multiple categories
  */
+/*!
+ * \qmlproperty string Ribbon::id
+ * This property holds the id of the ribbon.
+ */
 /*!
  * \qmlproperty RibbonMenu Ribbon::menu
  * This property holds the menu of the ribbon.