docs: review the Utils API

Ensure documentation is up to date, and log is not missing. Related to KDAB#54
narnaud · Jul 5, 2024 · e40afb5 · e40afb5
1 parent 88acff0
commit e40afb5
Show file tree

Hide file tree

Showing 14 changed files with 30 additions and 17 deletions.
diff --git a/docs/API/script/dir.md b/docs/API/script/dir.md
@@ -37,7 +37,7 @@ import Script
 
 ## Detailed Description
 
-The `Dir` singleton implements most of the static methods from `QDir`, check [QDir](https://doc.qt.io/qt-5/qdir.html)
+The `Dir` singleton implements most of the static methods from `QDir`, check [QDir](https://doc.qt.io/qt-6/qdir.html)
 documentation.
 
 ## Property Documentation

diff --git a/docs/API/script/file.md b/docs/API/script/file.md
@@ -20,7 +20,7 @@ import Script
 ## Detailed Description
 
 The `File` singleton implements most of the static methods from `QFile`, check
-[QFile](https://doc.qt.io/qt-5/qfile.html) documentation.
+[QFile](https://doc.qt.io/qt-6/qfile.html) documentation.
 
 ## Method Documentation
 

diff --git a/docs/API/script/fileinfo.md b/docs/API/script/fileinfo.md
@@ -16,7 +16,7 @@ import Script
 ## Detailed Description
 
 The `FileInfo` singleton implements most of the static methods from `QFileInfo`, check
-[QFileInfo](https://doc.qt.io/qt-5/qfileinfo.html) documentation.
+[QFileInfo](https://doc.qt.io/qt-6/qfileinfo.html) documentation.
 
 ## Method Documentation
 

diff --git a/docs/API/script/qdirvaluetype.md b/docs/API/script/qdirvaluetype.md
@@ -43,7 +43,7 @@ import Script
 
 ## Detailed Description
 
-The `QDirValueType` is a wrapper around the `QDir` C++ class, check [QDir](https://doc.qt.io/qt-5/qdir.html)
+The `QDirValueType` is a wrapper around the `QDir` C++ class, check [QDir](https://doc.qt.io/qt-6/qdir.html)
 documentation. It can only be created using [Dir](dir.md) singleton.
 
 ## Property Documentation

diff --git a/docs/API/script/qfileinfovaluetype.md b/docs/API/script/qfileinfovaluetype.md
@@ -49,7 +49,7 @@ import Script
 ## Detailed Description
 
 The `QFileInfoValueType` is a wrapper around the `QFileInfo` C++ class, check
-[QFileInfo](https://doc.qt.io/qt-5/qfileinfo.html) documentation. It can only be created using
+[QFileInfo](https://doc.qt.io/qt-6/qfileinfo.html) documentation. It can only be created using
 [FileInfo](fileinfo.md].
 
 ## Property Documentation

diff --git a/docs/API/script/userdialog.md b/docs/API/script/userdialog.md
@@ -26,13 +26,13 @@ import Script
 The `UserDialog` singleton provides methods to display common dialog that could be used in
 scripts. If the user cancel the dialog, it will return a null value you can test directly:
 
-````
-var s = UserDialog.getText("Get text", "Value")
+```js
+let s = UserDialog.getText("Get text", "Value")
 if (s !== null)
     Message.log("Text: " + s)
 else
     Message.log("Cancelled")
-````
+```
 
 ## Method Documentation
 

diff --git a/src/core/dir.cpp b/src/core/dir.cpp
@@ -21,7 +21,7 @@ namespace Core {
  * \inqmlmodule Script
  * \ingroup Utilities
  *
- * The `Dir` singleton implements most of the static methods from `QDir`, check [QDir](https://doc.qt.io/qt-5/qdir.html)
+ * The `Dir` singleton implements most of the static methods from `QDir`, check [QDir](https://doc.qt.io/qt-6/qdir.html)
  * documentation.
  */
 

diff --git a/src/core/dir.h b/src/core/dir.h
@@ -73,7 +73,7 @@ class Dir : public QObject
     Q_ENUM(SortFlag)
     Q_DECLARE_FLAGS(SortFlags, SortFlag)
 
-    Q_INVOKABLE QChar separator() const;
+    QChar separator() const;
 
     Q_INVOKABLE inline Core::QDirValueType current() const { return QDirValueType(currentPath()); }
     QString currentPath() const;

diff --git a/src/core/file.cpp b/src/core/file.cpp
@@ -23,7 +23,7 @@ namespace Core {
  * \ingroup Utilities
  *
  * The `File` singleton implements most of the static methods from `QFile`, check
- * [QFile](https://doc.qt.io/qt-5/qfile.html) documentation.
+ * [QFile](https://doc.qt.io/qt-6/qfile.html) documentation.
  */
 
 File::File(QObject *parent)

diff --git a/src/core/fileinfo.cpp b/src/core/fileinfo.cpp
@@ -22,7 +22,7 @@ namespace Core {
  * \ingroup Utilities
  *
  * The `FileInfo` singleton implements most of the static methods from `QFileInfo`, check
- * [QFileInfo](https://doc.qt.io/qt-5/qfileinfo.html) documentation.
+ * [QFileInfo](https://doc.qt.io/qt-6/qfileinfo.html) documentation.
  */
 
 FileInfo::FileInfo(QObject *parent)

diff --git a/src/core/qdirvaluetype.cpp b/src/core/qdirvaluetype.cpp
@@ -19,7 +19,7 @@ namespace Core {
  * \ingroup Utilities/@last
  * \sa Dir
  *
- * The `QDirValueType` is a wrapper around the `QDir` C++ class, check [QDir](https://doc.qt.io/qt-5/qdir.html)
+ * The `QDirValueType` is a wrapper around the `QDir` C++ class, check [QDir](https://doc.qt.io/qt-6/qdir.html)
  * documentation. It can only be created using [Dir](dir.md) singleton.
  */
 

diff --git a/src/core/qfileinfovaluetype.cpp b/src/core/qfileinfovaluetype.cpp
@@ -20,7 +20,7 @@ namespace Core {
  * \sa FileInfo
  *
  * The `QFileInfoValueType` is a wrapper around the `QFileInfo` C++ class, check
- * [QFileInfo](https://doc.qt.io/qt-5/qfileinfo.html) documentation. It can only be created using
+ * [QFileInfo](https://doc.qt.io/qt-6/qfileinfo.html) documentation. It can only be created using
  * [FileInfo](fileinfo.md].
  */
 

diff --git a/src/core/userdialog.cpp b/src/core/userdialog.cpp
@@ -9,6 +9,7 @@
 */
 
 #include "userdialog.h"
+#include "logger.h"
 
 #include <QApplication>
 #include <QFileDialog>
@@ -27,13 +28,13 @@ namespace Core {
  * The `UserDialog` singleton provides methods to display common dialog that could be used in
  * scripts. If the user cancel the dialog, it will return a null value you can test directly:
  *
- * ````
- * var s = UserDialog.getText("Get text", "Value")
+ * ```js
+ * let s = UserDialog.getText("Get text", "Value")
  * if (s !== null)
  *     Message.log("Text: " + s)
  * else
  *     Message.log("Cancelled")
- * ````
+ * ```
  */
 
 UserDialog::UserDialog(QQmlEngine *parent)
@@ -50,6 +51,7 @@ UserDialog::UserDialog(QQmlEngine *parent)
  */
 QJSValue UserDialog::getOpenFileName(const QString &caption, const QString &dir, const QString &filters)
 {
+    LOG("UserDialog::getOpenFileName", caption, dir, filters);
     const QString s = QFileDialog::getOpenFileName(dialogParent(), caption, dir, filters);
     if (!s.isEmpty())
         return s;
@@ -65,6 +67,7 @@ QJSValue UserDialog::getOpenFileName(const QString &caption, const QString &dir,
  */
 QJSValue UserDialog::getSaveFileName(const QString &caption, const QString &dir, const QString &filters)
 {
+    LOG("UserDialog::getSaveFileName", caption, dir, filters);
     const QString s = QFileDialog::getSaveFileName(dialogParent(), caption, dir, filters);
     if (!s.isEmpty())
         return s;
@@ -79,6 +82,7 @@ QJSValue UserDialog::getSaveFileName(const QString &caption, const QString &dir,
  */
 QJSValue UserDialog::getExistingDirectory(const QString &caption, const QString &dir)
 {
+    LOG("UserDialog::getExistingDirectory", caption, dir);
     const QString s = QFileDialog::getExistingDirectory(dialogParent(), caption, dir);
     if (!s.isEmpty())
         return s;
@@ -98,6 +102,7 @@ QJSValue UserDialog::getExistingDirectory(const QString &caption, const QString
 QJSValue UserDialog::getItem(const QString &title, const QString &label, const QStringList &items, int current,
                              bool editable)
 {
+    LOG("UserDialog::getItem", title, label, items, current, editable);
     bool ok;
     const QString ret = QInputDialog::getItem(dialogParent(), title, label, items, current, editable, &ok);
     if (ok)
@@ -119,6 +124,7 @@ QJSValue UserDialog::getItem(const QString &title, const QString &label, const Q
 QJSValue UserDialog::getDouble(const QString &title, const QString &label, double value, int decimals, double step,
                                double min, double max)
 {
+    LOG("UserDialog::getDouble", title, label, value, decimals, step, min, max);
     bool ok;
     const double ret =
         QInputDialog::getDouble(dialogParent(), title, label, value, min, max, decimals, &ok, Qt::WindowFlags(), step);
@@ -139,6 +145,7 @@ QJSValue UserDialog::getDouble(const QString &title, const QString &label, doubl
 // clang-format on
 QJSValue UserDialog::getInt(const QString &title, const QString &label, int value, int step, int min, int max)
 {
+    LOG("UserDialog::getInt", title, label, value, step, min, max);
     bool ok;
     const int ret = QInputDialog::getInt(dialogParent(), title, label, value, min, max, step, &ok);
     if (ok)
@@ -155,6 +162,7 @@ QJSValue UserDialog::getInt(const QString &title, const QString &label, int valu
  */
 QJSValue UserDialog::getText(const QString &title, const QString &label, const QString &text)
 {
+    LOG("UserDialog::getText", title, label, text);
     bool ok;
     const QString ret = QInputDialog::getText(dialogParent(), title, label, QLineEdit::Normal, text, &ok);
     if (ok)
@@ -168,6 +176,7 @@ QJSValue UserDialog::getText(const QString &title, const QString &label, const Q
  */
 void UserDialog::information(const QString &title, const QString &text)
 {
+    LOG("UserDialog::information", title, text);
     QMessageBox::information(dialogParent(), title, text);
 }
 
@@ -177,6 +186,7 @@ void UserDialog::information(const QString &title, const QString &text)
  */
 void UserDialog::warning(const QString &title, const QString &text)
 {
+    LOG("UserDialog::warning", title, text);
     QMessageBox::warning(dialogParent(), title, text);
 }
 
@@ -186,6 +196,7 @@ void UserDialog::warning(const QString &title, const QString &text)
  */
 void UserDialog::critical(const QString &title, const QString &text)
 {
+    LOG("UserDialog::critical", title, text);
     QMessageBox::critical(dialogParent(), title, text);
 }
 

diff --git a/src/core/utils.cpp b/src/core/utils.cpp
@@ -204,6 +204,7 @@ void Utils::copyToClipboard(const QString &text)
 // The readonly C++ attribute has the same functionality as the readonly MIDL attribute.
 QStringList Utils::cppKeywords()
 {
+    LOG("Utils::cppKeywords");
     return QStringList {"alignas",
                         "alignof",
                         "and",
@@ -299,6 +300,7 @@ QStringList Utils::cppKeywords()
  */
 QStringList Utils::cppPrimitiveTypes()
 {
+    LOG("Utils::cppPrimitiveTypes");
     return QStringList {"int",  "long",    "short",    "void",     "float",  "double",
                         "char", "char8_t", "char16_t", "char32_t", "wchar_t"};
 }