gtad.yaml, *.mustache: upgrade to GTAD 0.7 beta

That means much more readable templates thanks to GTAD 0.7 in turn using
the upgrade Mustache engine.

3 files changed, 200 insertions, 136 deletions

diff --git a/lib/csapi/gtad.yaml b/lib/csapi/gtad.yaml
index 6d4e080f..086bd4f7 100644
--- a/lib/csapi/gtad.yaml
+++ b/lib/csapi/gtad.yaml
@@ -145,6 +145,18 @@ mustache:
     joinedParamDef: '{{>maybeCrefType}} {{paramName}}{{>cjoin}}'
     passQueryParams: '{{#queryParams}}{{paramName}}{{>cjoin}}{{/queryParams}}'
 
+    # Doc-comment blocks. Comment indent is managed by clang-format
+    # (without clang-format there'd have to be a separate partial definition
+    # for each indent...)
+
+    # For structures that are not supposed to have a summary (e.g., JSON schema)
+    docCommentShort: |-
+      {{#description}}
+      /// {{_}}{{/description}}
+    docCommentSummary: |-
+      {{#summary}} \brief {{summary}}
+       *{{/summary}}
+
   templates:
   - "{{base}}.h.mustache"
   - "{{base}}.cpp.mustache"
diff --git a/lib/csapi/{{base}}.cpp.mustache b/lib/csapi/{{base}}.cpp.mustache
index 6cbd1b65..b3bd4de9 100644
--- a/lib/csapi/{{base}}.cpp.mustache
+++ b/lib/csapi/{{base}}.cpp.mustache
@@ -3,74 +3,84 @@
 {{^models}}
 #include "converters.h"{{/models}}
 {{#operations}}
-{{#producesNonJson?}}
+    {{#producesNonJson?}}
 #include <QtNetwork/QNetworkReply>
-{{/producesNonJson?}}
+    {{/producesNonJson?}}
 #include <QtCore/QStringBuilder>
 {{/operations}}
+
 using namespace Quotient;
+
 {{#models.model}}
     {{#in?}}
-void JsonObjectConverter<{{qualifiedName}}>::dumpTo(QJsonObject& jo, const {{qualifiedName}}& pod)
-{
-{{#propertyMap
-}}    fillJson(jo, pod.{{nameCamelCase}});
-{{/propertyMap}}{{#parents
-}}    fillJson<{{name}}>(jo, pod);
-{{/parents}}{{#vars
-}}    addParam<{{^required?}}IfNotEmpty{{/required?}}>(jo, QStringLiteral("{{baseName}}"), pod.{{nameCamelCase}});
-{{/vars}}
+void JsonObjectConverter<{{qualifiedName}}>::dumpTo(
+        QJsonObject& jo, const {{qualifiedName}}& pod)
+{       {{#propertyMap}}
+    fillJson(jo, pod.{{nameCamelCase}});
+        {{/propertyMap}}{{#parents}}
+    fillJson<{{name}}>(jo, pod);
+        {{/parents}}{{#vars}}
+    addParam<{{^required?}}IfNotEmpty{{/required?}}>(jo,
+            QStringLiteral("{{baseName}}"), pod.{{nameCamelCase}});
+        {{/vars}}
 }
-    {{/in?}}{{#out?}}
-void JsonObjectConverter<{{qualifiedName}}>::fillFrom({{>maybeCrefJsonObject}} jo, {{qualifiedName}}& result)
-{
-{{#parents
-}}    fillFromJson<{{qualifiedName}}>(jo, result);
-{{/parents}}{{#vars
-}}    fromJson(jo.{{>takeOrValue}}("{{baseName}}"_ls), result.{{nameCamelCase}});
-{{/vars}}{{#propertyMap
-}}    fromJson(jo, result.{{nameCamelCase}});
-{{/propertyMap}}
+    {{/in?}}
+
+    {{#out?}}
+void JsonObjectConverter<{{qualifiedName}}>::fillFrom(
+        {{>maybeCrefJsonObject}} jo, {{qualifiedName}}& result)
+{       {{#parents}}
+    fillFromJson<{{qualifiedName}}>(jo, result);
+        {{/parents}}{{#vars}}
+    fromJson(jo.{{>takeOrValue}}("{{baseName}}"_ls), result.{{nameCamelCase}});
+        {{/vars}}{{#propertyMap}}
+    fromJson(jo, result.{{nameCamelCase}});
+        {{/propertyMap}}
 }
     {{/out?}}
+
 {{/models.model}}
 {{#operations}}
+
 static const auto basePath = QStringLiteral("{{basePathWithoutHost}}");
     {{#operation}}{{#models}}
+
 // Converters
-namespace Quotient
-{
+namespace Quotient {
         {{#model}}
-template <> struct JsonObjectConverter<{{qualifiedName}}>
-{
-            {{#in?
-}}    static void dumpTo(QJsonObject& jo, const {{qualifiedName}}& pod)
-    {
-{{#propertyMap
-}}        fillJson(jo, pod.{{nameCamelCase}});
-{{/propertyMap}}{{#parents
-}}        fillJson<{{name}}>(jo, pod);
-{{/parents}}{{#vars
-}}        addParam<{{^required?}}IfNotEmpty{{/required?}}>(jo, QStringLiteral("{{baseName}}"), pod.{{nameCamelCase}});
-{{/vars}}
+
+template <> struct JsonObjectConverter<{{qualifiedName}}> {
+            {{#in?}}
+    static void dumpTo(QJsonObject& jo, const {{qualifiedName}}& pod)
+    {           {{#propertyMap}}
+        fillJson(jo, pod.{{nameCamelCase}});
+                {{/propertyMap}}{{#parents}}
+        fillJson<{{name}}>(jo, pod);
+                {{/parents}}{{#vars}}
+        addParam<{{^required?}}IfNotEmpty{{/required?}}>(jo,
+                    QStringLiteral("{{baseName}}"), pod.{{nameCamelCase}});
+                {{/vars}}
     }
-            {{/in?}}{{#out?
-}}    static void fillFrom({{>maybeCrefJsonObject}} jo, {{qualifiedName}}& result)
-    {
-{{#parents
-}}        fillFromJson<{{qualifiedName}}{{!of the parent!}}>(jo, result);
-{{/parents}}{{#vars
-}}        fromJson(jo.{{>takeOrValue}}("{{baseName}}"_ls), result.{{nameCamelCase}});
-{{/vars}}{{#propertyMap
-}}        fromJson(jo, result.{{nameCamelCase}});
-{{/propertyMap}}
+            {{/in?}}
+            {{#out?}}
+    static void fillFrom({{>maybeCrefJsonObject}} jo, {{qualifiedName}}& result)
+    {           {{#parents}}
+        fillFromJson<{{qualifiedName}}{{!of the parent!}}>(jo, result);
+                {{/parents}}{{#vars}}
+        fromJson(jo.{{>takeOrValue}}("{{baseName}}"_ls),
+                 result.{{nameCamelCase}});
+                {{/vars}}{{#propertyMap}}
+        fromJson(jo, result.{{nameCamelCase}});
+                {{/propertyMap}}
     }
             {{/out?}}
 };
         {{/model}}
-} // namespace QMatrixClient
+
+} // namespace Quotient
     {{/models}}
     {{#responses}}{{#normalResponse?}}{{#allProperties?}}
+
 class {{camelCaseOperationId}}Job::Private
 {
     public:{{#allProperties}}
@@ -78,76 +88,94 @@ class {{camelCaseOperationId}}Job::Private
 };
     {{/allProperties?}}{{/normalResponse?}}{{/responses}}
     {{#queryParams?}}
-BaseJob::Query queryTo{{camelCaseOperationId}}({{#queryParams}}{{>joinedParamDef}}{{/queryParams}})
+
+BaseJob::Query queryTo{{camelCaseOperationId}}(
+            {{#queryParams}}{{>joinedParamDef}}{{/queryParams}})
 {
     BaseJob::Query _q;{{#queryParams}}
-    addParam<{{^required?}}IfNotEmpty{{/required?}}>(_q, QStringLiteral("{{baseName}}"), {{paramName}});{{/queryParams}}
+    addParam<{{^required?}}IfNotEmpty{{/required?}}>(_q,
+            QStringLiteral("{{baseName}}"), {{paramName}});{{/queryParams}}
     return _q;
 }
     {{/queryParams?}}
     {{^bodyParams}}
-QUrl {{camelCaseOperationId}}Job::makeRequestUrl(QUrl baseUrl{{#allParams?}}, {{#allParams}}{{>joinedParamDef}}{{/allParams}}{{/allParams?}})
+
+QUrl {{camelCaseOperationId}}Job::makeRequestUrl(QUrl baseUrl{{#allParams?}},
+        {{#allParams}}{{>joinedParamDef}}{{/allParams}}{{/allParams?}})
 {
     return BaseJob::makeRequestUrl(std::move(baseUrl),
             basePath{{#pathParts}} % {{_}}{{/pathParts}}{{#queryParams?}},
             queryTo{{camelCaseOperationId}}({{>passQueryParams}}){{/queryParams?}});
-}
-    {{/bodyParams}}
-static const auto {{camelCaseOperationId}}JobName = QStringLiteral("{{camelCaseOperationId}}Job");
-
-{{camelCaseOperationId}}Job::{{camelCaseOperationId}}Job({{#allParams}}{{>joinedParamDef}}{{/allParams}})
-    : BaseJob(HttpVerb::{{#_cap}}{{#_tolower}}{{httpMethod}}{{/_tolower}}{{/_cap}}, {{camelCaseOperationId}}JobName,
-        basePath{{#pathParts}} % {{_}}{{/pathParts}}{{#queryParams?}},
-        queryTo{{camelCaseOperationId}}({{>passQueryParams}}){{/queryParams?}}{{#skipAuth}}{{#queryParams?}},
-        {}{{/queryParams?}}, false{{/skipAuth}}){{#responses}}{{#normalResponse?}}{{#allProperties?}}
-    , d(new Private){{/allProperties?}}{{/normalResponse?}}{{/responses}}
-{
-{{#headerParams?}}{{#headerParams
-}}    setRequestHeader("{{baseName}}", {{paramName}}.toLatin1());{{/headerParams}}
-{{/headerParams?}}{{#bodyParams?
-}}{{#inlineBody
-}}    setRequestData(Data({{#consumesNonJson?}}{{nameCamelCase}}{{/consumesNonJson?
-                        }}{{^consumesNonJson?}}toJson({{nameCamelCase}}){{/consumesNonJson?}}));
-{{/inlineBody}}{{^inlineBody
-}}    QJsonObject _data;{{#bodyParams}}
-    addParam<{{^required?}}IfNotEmpty{{/required?}}>(_data, QStringLiteral("{{baseName}}"), {{paramName}});{{/bodyParams}}
+}   {{/bodyParams}}
+
+{{camelCaseOperationId}}Job::{{camelCaseOperationId}}Job(
+        {{#allParams}}{{>joinedParamDef}}{{/allParams}})
+    : BaseJob(HttpVerb::{{#_cap}}{{#_tolower}}{{httpMethod}}{{/_tolower}}{{/_cap}},
+            QStringLiteral("{{camelCaseOperationId}}Job"), {{!object name}}
+            basePath{{#pathParts}} % {{_}}{{/pathParts}}   {{!API endpoint}}
+    {{#queryParams?
+    }}      , queryTo{{camelCaseOperationId}}({{>passQueryParams}})
+    {{/queryParams?
+    }}{{#skipAuth}}{{#queryParams?}}, {}{{/queryParams?}}, false{{/skipAuth}} )
+    {{#responses}}{{#normalResponse?}}{{#allProperties?
+    }}, d(new Private){{/allProperties?}}{{/normalResponse?}}{{/responses}}
+{       {{#headerParams}}
+    setRequestHeader("{{baseName}}", {{paramName}}.toLatin1());
+        {{/headerParams}}{{#bodyParams?}}
+            {{#inlineBody}}
+    setRequestData(Data({{!avoid extra linebreaks}}{{
+            #consumesNonJson?}}{{nameCamelCase}}{{/consumesNonJson?}}{{
+            ^consumesNonJson?}}toJson({{nameCamelCase}}){{/consumesNonJson?
+        }}));
+            {{/inlineBody}}{{^inlineBody}}
+    QJsonObject _data;
+                {{#bodyParams}}
+    addParam<{{^required?}}IfNotEmpty{{/required?}}>(_data,
+                            QStringLiteral("{{baseName}}"), {{paramName}});
+                {{/bodyParams}}
     setRequestData(_data);
-{{/inlineBody}}{{/bodyParams?
-}}{{#producesNonJson?
-}}    setExpectedContentTypes({ {{#produces}}"{{_}}"{{>cjoin}}{{/produces}} });
-{{/producesNonJson?}}
+            {{/inlineBody}}
+        {{/bodyParams?}}{{#producesNonJson?}}
+    setExpectedContentTypes({ {{#produces}}"{{_}}"{{>cjoin}}{{/produces}} });
+        {{/producesNonJson?}}
 }
     {{#responses}}{{#normalResponse?}}{{#allProperties?}}
+
 {{camelCaseOperationId}}Job::~{{camelCaseOperationId}}Job() = default;
         {{#allProperties}}
-{{>qualifiedMaybeCrefType}} {{camelCaseOperationId}}Job::{{paramName}}(){{^moveOnly}} const{{/moveOnly}}
+
+{{>qualifiedMaybeCrefType}}
+    {{camelCaseOperationId}}Job::{{paramName}}(){{^moveOnly}} const{{/moveOnly}}
 {
     return {{#moveOnly}}std::move({{/moveOnly}}d->{{paramName}}{{#moveOnly}}){{/moveOnly}};
 }
         {{/allProperties}}
+
         {{#producesNonJson?}}
 BaseJob::Status {{camelCaseOperationId}}Job::parseReply(QNetworkReply* reply)
 {
-    {{#headers}}d->{{paramName}} = reply->rawHeader("{{baseName}}");{{! We don't check for required headers yet }}
+    {{! We don't check for required headers yet }}
+    {{#headers}}d->{{paramName}} = reply->rawHeader("{{baseName}}");
     {{/headers}}{{#properties}}d->{{paramName}} = reply;{{/properties}}
     return Success;
 }
         {{/producesNonJson?}}{{^producesNonJson?}}
 BaseJob::Status {{camelCaseOperationId}}Job::parseJson(const QJsonDocument& data)
 {
-{{#inlineResponse
-}}    fromJson(data, d->{{paramName}});
-{{/inlineResponse}}{{^inlineResponse
-}}    auto json = data.object();
-{{#    properties}}{{#required?
-}}    if (!json.contains("{{baseName}}"_ls))
+            {{#inlineResponse}}
+    fromJson(data, d->{{paramName}});
+            {{/inlineResponse}}{{^inlineResponse}}
+    auto json = data.object();
+                {{#properties}}{{#required?}}
+    if (!json.contains("{{baseName}}"_ls))
         return { IncorrectResponse,
             "The key '{{baseName}}' not found in the response" };
-{{/required?
-}}    fromJson(json.value("{{baseName}}"_ls), d->{{paramName}});
-{{/    properties}}
-{{/inlineResponse
-}}    return Success;
+                    {{/required?}}
+    fromJson(json.value("{{baseName}}"_ls), d->{{paramName}});
+                {{/properties}}
+            {{/inlineResponse}}
+
+    return Success;
 }
         {{/producesNonJson?}}
     {{/allProperties?}}{{/normalResponse?}}{{/responses}}
diff --git a/lib/csapi/{{base}}.h.mustache b/lib/csapi/{{base}}.h.mustache
index 56044e7d..404aafe8 100644
--- a/lib/csapi/{{base}}.h.mustache
+++ b/lib/csapi/{{base}}.h.mustache
@@ -8,88 +8,112 @@
 {{#imports}}
 #include {{_}}{{/imports}}
 
-namespace Quotient
-{
+namespace Quotient {
 {{#models}}
+
 // Data structures
-{{#    model}}
-{{#description}}/// {{_}}{{/description}}
+
+    {{#model}}
+{{>docCommentShort}}
 struct {{name}}{{#parents?}} : {{#parents}}{{name}}{{>cjoin}}{{/parents}}{{/parents?}}
-{
-{{#    vars}}{{#description?}}    /// {{#description}}{{_}}{{/description}}{{/description?}}
+{       {{#vars}}
+
+    {{>docCommentShort}}
     {{>maybeOmittableType}} {{nameCamelCase}};
-{{/    vars}}
-{{#    propertyMap}}
-{{#description?}}    /// {{#description}}{{_}}{{/description}}{{/description?}}
+        {{/vars}}{{#propertyMap}}
+
+    {{>docCommentShort}}
     {{>maybeOmittableType}} {{nameCamelCase}};
-{{/    propertyMap}}
+        {{/propertyMap}}
 };
 
 template <> struct JsonObjectConverter<{{name}}>
 {
-    {{#in?}}static void dumpTo(QJsonObject& jo, const {{name}}& pod);{{/in?}}
-    {{#out?}}static void fillFrom({{>maybeCrefJsonObject}} jo, {{name}}& pod);{{/out?}}};
-{{/    model}}
+        {{#in?}}
+    static void dumpTo(QJsonObject& jo, const {{name}}& pod);
+        {{/in?}}
+        {{#out?}}
+    static void fillFrom({{>maybeCrefJsonObject}} jo, {{name}}& pod);
+        {{/out?}}
+};
+    {{/model}}
 {{/models}}
-{{#operations}}// Operations
-{{#    operation}}
-{{#summary}}/// {{summary}}{{/summary}}
-{{#description?}}/*!{{#description}}
+{{#operations}}
+
+// Operations
+    {{#operation}}
+
+/*!{{>docCommentSummary}}{{#description}}
  * {{_}}{{/description}}
- */{{/description?}}
-class {{camelCaseOperationId}}Job : public BaseJob
-{
-public:{{#models}}
+ */
+class {{camelCaseOperationId}}Job : public BaseJob {
+public: {{#models}}
     // Inner data structures
-{{#            model}}
-{{#description?}}    /// {{#description}}{{_}}{{/description}}{{/description?}}
-    struct {{name}}{{#parents?}} : {{#parents}}{{name}}{{>cjoin}}{{/parents}}{{/parents?}}
+            {{#model}}
+
+    {{>docCommentShort}}
+    struct {{name}}{{#parents?}} :
+        {{#parents}}{{name}}{{>cjoin}}{{/parents}}{{/parents?}}
     {
-{{#                vars}}{{#description?}}        /// {{#description}}{{_}}{{/description}}{{/description?}}
+                {{#vars}}
+        {{>docCommentShort}}
         {{>maybeOmittableType}} {{nameCamelCase}};
-{{/                vars}}
-{{#                propertyMap}}
-{{#description?}}        /// {{#description}}{{_}}{{/description}}{{/description?}}
+                {{/vars}}
+                {{#propertyMap}}
+        {{>docCommentShort}}
         {{>maybeOmittableType}} {{nameCamelCase}};
-{{/                propertyMap}}
+                {{/propertyMap}}
     };
-{{/            model}}
+            {{/model}}
+
     // Construction/destruction
-{{/        models}}{{#allParams?}}
-    /*! {{summary}}{{#allParams}}
+
+        {{/models}}
+        {{^allParams?}}
+            {{#summary}}
+    /// {{summary}}
+            {{/summary}}
+        {{/allParams?}}{{#allParams?}}
+    /*!{{>docCommentSummary}}
+            {{#allParams}}
      * \param {{nameCamelCase}}{{#description}}
-     *   {{_}}{{/description}}{{/allParams}}
-     */{{/allParams?}}
+     *   {{_}}{{/description}}
+            {{/allParams}}
+     */
+        {{/allParams?}}
     explicit {{camelCaseOperationId}}Job({{#allParams}}{{>joinedParamDecl}}{{/allParams}});
-{{^        bodyParams}}
+        {{^bodyParams}}
 
-    /*! Construct a URL without creating a full-fledged job object
+    /*! \brief Construct a URL without creating a full-fledged job object
      *
-     * This function can be used when a URL for
-     * {{camelCaseOperationId}}Job is necessary but the job
-     * itself isn't.
+     * This function can be used when a URL for {{camelCaseOperationId}}Job
+     * is necessary but the job itself isn't.
      */
-    static QUrl makeRequestUrl(QUrl baseUrl{{#allParams?}}, {{#allParams}}{{>joinedParamDecl}}{{/allParams}}{{/allParams?}});
-{{/        bodyParams}}
-{{#        responses}}{{#normalResponse?}}{{#allProperties?}}
+    static QUrl makeRequestUrl(QUrl baseUrl{{#allParams?}},
+                    {{#allParams}}{{>joinedParamDecl}}{{/allParams}}{{/allParams?}});
+        {{/bodyParams}}
+        {{#responses}}{{#normalResponse?}}{{#allProperties?}}
     ~{{camelCaseOperationId}}Job() override;
 
     // Result properties
-{{#allProperties}}{{#description}}
-    /// {{_}}{{/description}}
-    {{>maybeCrefType}} {{paramName}}(){{^moveOnly}} const{{/moveOnly}};{{/allProperties}}
+            {{#allProperties}}
 
-protected:{{#producesNonJson?}}
+    {{>docCommentShort}}
+    {{>maybeCrefType}} {{paramName}}(){{^moveOnly}} const{{/moveOnly}};
+            {{/allProperties}}
+
+protected:  {{#producesNonJson?}}
     Status parseReply(QNetworkReply* reply) override;
-{{/producesNonJson?}}{{^producesNonJson?}}
+            {{/producesNonJson?}}{{^producesNonJson?}}
     Status parseJson(const QJsonDocument& data) override;
-{{/producesNonJson?}}
+            {{/producesNonJson?}}
 
 private:
     class Private;
     QScopedPointer<Private> d;
-{{/        allProperties?}}{{/normalResponse?}}{{/responses}}
+        {{/allProperties?}}{{/normalResponse?}}{{/responses}}
 };
-{{/    operation}}
+    {{/operation}}
 {{/operations}}
+
 } // namespace Quotient