PluginSpec: Add a "LongDescription" to plugin meta data

The EmacsKeys plugin had a long description with details on what it
does, which in principle is a good thing, but shouldn't be shown with
e.g. the -version command line argument.

Split the description in a short "Description" (name unchanged for
compatibility), and a possibly longer "LongDescription", using only the
first one for -version, and showing both in the plugin details.

Adapt the EmacsKeys plugin meta data.

Fixes: QTCREATORBUG-17312
Change-Id: I4a4abf51e5e19b71ee73edb14c6a897fbceaf916
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: <github-actions-qt-creator@cristianadam.eu>
Reviewed-by: David Schulz <david.schulz@qt.io>

doc/qtcreatordev/src/plugin-metadata.qdoc

@@ -103,8 +103,13 @@
                 designed for long texts.
         \row
             \li Description
+            \li String
+            \li Short description of what the plugin is supposed to provide.
+                This is shown when running \QC with \c{-version}.
+        \row
+            \li LongDescription
             \li String or array of strings
-            \li Possibly multi-line description of what the plugin is supposed
+            \li Possibly multi-line, more extensive description of what the plugin is supposed
                 to provide.
                 Should still be kept relatively short, since the UI is not
                 designed for long texts.

src/libs/extensionsystem/plugindetailsview.cpp

@@ -56,6 +56,7 @@ public:
     {
         using namespace Utils::Layouting;
 
+        // clang-format off
         Form {
             tr("Name:"), name, br,
             tr("Version:"), version, br,
@@ -70,6 +71,7 @@ public:
             tr("License:"), license, br,
             tr("Dependencies:"), dependencies
         }.attachTo(q, WithoutMargins);
+        // clang-format on
     }
 
     PluginDetailsView *q = nullptr;
@@ -144,7 +146,11 @@ void PluginDetailsView::update(PluginSpec *spec)
     const QString platformString = tr("%1 (current: \"%2\")")
                                    .arg(platform, PluginManager::platformName());
     d->platforms->setText(platformString);
-    d->description->setText(spec->description());
+    QString description = spec->description();
+    if (!description.isEmpty() && !spec->longDescription().isEmpty())
+        description += "\n\n";
+    description += spec->longDescription();
+    d->description->setText(description);
     d->copyright->setText(spec->copyright());
     d->license->setText(spec->license());
     d->dependencies->addItems(Utils::transform<QList>(spec->dependencies(),

src/libs/extensionsystem/pluginspec.cpp

@@ -248,6 +248,15 @@ QString PluginSpec::description() const
     return d->description;
 }
 
+/*!
+    Returns the plugin's long description. This is valid after the PluginSpec::Read
+    state is reached.
+*/
+QString PluginSpec::longDescription() const
+{
+    return d->longDescription;
+}
+
 /*!
     Returns the plugin URL where you can find more information about the plugin.
     This is valid after the PluginSpec::Read state is reached.
@@ -560,6 +569,7 @@ namespace {
     const char COPYRIGHT[] = "Copyright";
     const char LICENSE[] = "License";
     const char DESCRIPTION[] = "Description";
+    const char LONGDESCRIPTION[] = "LongDescription";
     const char URL[] = "Url";
     const char CATEGORY[] = "Category";
     const char PLATFORM[] = "Platform";
@@ -591,6 +601,7 @@ void PluginSpecPrivate::reset()
     copyright.clear();
     license.clear();
     description.clear();
+    longDescription.clear();
     url.clear();
     category.clear();
     location.clear();
@@ -795,6 +806,10 @@ bool PluginSpecPrivate::readMetaData(const QJsonObject &pluginMetaData)
     if (!value.isUndefined() && !Utils::readMultiLineString(value, &description))
         return reportError(msgValueIsNotAString(DESCRIPTION));
 
+    value = metaData.value(QLatin1String(LONGDESCRIPTION));
+    if (!value.isUndefined() && !Utils::readMultiLineString(value, &longDescription))
+        return reportError(msgValueIsNotAString(LONGDESCRIPTION));
+
     value = metaData.value(QLatin1String(URL));
     if (!value.isUndefined() && !value.isString())
         return reportError(msgValueIsNotAString(URL));

src/libs/extensionsystem/pluginspec.h

@@ -68,6 +68,7 @@ public:
     QString copyright() const;
     QString license() const;
     QString description() const;
+    QString longDescription() const;
     QString url() const;
     QString category() const;
     QString revision() const;

src/libs/extensionsystem/pluginspec_p.h

@@ -60,6 +60,7 @@ public:
     QString copyright;
     QString license;
     QString description;
+    QString longDescription;
     QString url;
     QString category;
     QRegularExpression platformSpecification;

src/plugins/emacskeys/EmacsKeys.json.in

@@ -13,7 +13,8 @@
                   \"\",
                   \"Alternatively, this plugin may be used under the terms of the GNU General Public License version 3 as published by the Free Software Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT included in the packaging of this plugin. Please review the following information to ensure the GNU General Public License requirements will be met: https://www.gnu.org/licenses/gpl-3.0.html.\"
     ],
-    \"Description\" : [
+    \"Description\" : \"Provides additional actions that typical Emacs users would expect.\",
+    \"LongDescription\" : [
         \"The main idea behind this plugin is to provide additional actions a typical emacs user would expect. It doesn\'t claim to provide full emacs emulation. The following actions are available:\",
         \" - Movement [C-f, C-b, C-n, C-p, M-f, M-b, C-a, C-e, M-<, M->]\",
         \" - Mark-based selection [C-SPC, C-x C-x]\",

tests/auto/extensionsystem/pluginspec/testspecs/spec1.json

@@ -11,7 +11,8 @@
             "blubbblubb",
             "end of terms"
         ],
-        "Description" : [
+        "Description" : "This plugin is just a test.",
+        "LongDescription" : [
             "This plugin is just a test.",
             "    it demonstrates the great use of the plugin spec."
         ],

tests/auto/extensionsystem/pluginspec/tst_pluginspec.cpp

@@ -99,7 +99,11 @@ void tst_PluginSpec::read()
     QCOMPARE(spec.vendor, QString("The Qt Company Ltd"));
     QCOMPARE(spec.copyright, QString("(C) 2015 The Qt Company Ltd"));
     QCOMPARE(spec.license, QString("This is a default license bla\nblubbblubb\nend of terms"));
-    QCOMPARE(spec.description, QString("This plugin is just a test.\n    it demonstrates the great use of the plugin spec."));
+    QCOMPARE(spec.description, QString("This plugin is just a test."));
+    QCOMPARE(
+        spec.longDescription,
+        QString(
+            "This plugin is just a test.\n    it demonstrates the great use of the plugin spec."));
     QCOMPARE(spec.url, QString("http://www.qt.io"));
     PluginDependency dep1;
     dep1.name = QString("SomeOtherPlugin");