Mime type conversion: clarify and clean up documentation

The converters need to be instantiated (which implicitly registers)
after QPA has been initialized, i.e. after QGuiApplication has been
instantiated. Clarify this in the documentation of the types.

Remove the dead documentation for the explicit registration function.
The API does not exist, and the documentation was never generated for
Qt 6 either. The function does not need to be called as long as new mime
converters are instantiated correctly (after QPA was initialized).

Pick-to: 6.6 6.5
Task-number: QTBUG-119216
Change-Id: I4e31b3773e88f7a6d579265f093bab46847cb028
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>

2 files changed, 17 insertions, 15 deletions

diff --git a/src/gui/platform/darwin/qmacmimeregistry.mm b/src/gui/platform/darwin/qmacmimeregistry.mm
index acbe671e1a..6710a0656f 100644
--- a/src/gui/platform/darwin/qmacmimeregistry.mm
+++ b/src/gui/platform/darwin/qmacmimeregistry.mm
@@ -21,20 +21,6 @@ Q_GLOBAL_STATIC(QStringList, globalDraggedTypesList)
 // implemented in qutimimeconverter.mm
 void registerBuiltInTypes();
 
-/*!
-    \fn void qRegisterDraggedTypes(const QStringList &types)
-    \relates QUtiMimeConverter
-
-    Registers the given \a types as custom pasteboard types.
-
-    This function should be called to enable the Drag and Drop events
-    for custom pasteboard types on Cocoa implementations. This is required
-    in addition to a QUtiMimeConverter subclass implementation. By default
-    drag and drop is enabled for all standard pasteboard types.
-
-   \sa QUtiMimeConverter
-*/
-
 void registerDraggedTypes(const QStringList &types)
 {
     (*globalDraggedTypesList()) += types;
diff --git a/src/gui/platform/darwin/qutimimeconverter.mm b/src/gui/platform/darwin/qutimimeconverter.mm
index 975f00cf88..6a4f80a8d7 100644
--- a/src/gui/platform/darwin/qutimimeconverter.mm
+++ b/src/gui/platform/darwin/qutimimeconverter.mm
@@ -53,7 +53,21 @@ using namespace Qt::StringLiterals;
     By subclasses this class, one can extend Qt's drag and drop
     and clipboard handling to convert to and from unsupported, or proprietary, UTI formats.
 
-    A subclass of QUtiMimeConverter will automatically be registered, and active, upon instantiation.
+    Construct an instance of your converter implementation after instantiating
+    QGuiApplication:
+
+    \code
+    int main(int argc, char **argv)
+    {
+        QGuiApplication app(argc, argv);
+        JsonMimeConverter jsonConverter;
+    }
+    \endcode
+
+    Destroying the instance will unregister the converter and remove support
+    for the conversion. It is also valid to heap-allocate the converter
+    instance; Qt takes ownership and will delete the converter object during
+    QGuiApplication shut-down.
 
     Qt has predefined support for the following UTIs:
     \list
@@ -94,6 +108,8 @@ QUtiMimeConverter::QUtiMimeConverter(HandlerScope scope)
 /*!
     Constructs a new conversion object and adds it to the
     globally accessed list of available converters.
+
+    Call this constructor after QGuiApplication has been created.
 */
 QUtiMimeConverter::QUtiMimeConverter()
     : QUtiMimeConverter(HandlerScopeFlag::All)