Cleanup; comments reformatting

2 files changed, 109 insertions, 113 deletions

diff --git a/lib/events/eventcontent.cpp b/lib/events/eventcontent.cpp
index 9d7edf20..479d5da0 100644
--- a/lib/events/eventcontent.cpp
+++ b/lib/events/eventcontent.cpp
@@ -29,12 +29,13 @@ FileInfo::FileInfo(const QFileInfo &fi)
 }
 
 FileInfo::FileInfo(QUrl u, qint64 payloadSize, const QMimeType& mimeType,
-                   Omittable<EncryptedFile> file, QString originalFilename)
+                   Omittable<EncryptedFile> encryptedFile,
+                   QString originalFilename)
     : mimeType(mimeType)
     , url(move(u))
     , payloadSize(payloadSize)
     , originalName(move(originalFilename))
-    , file(file)
+    , file(move(encryptedFile))
 {
     if (!isValid())
         qCWarning(MESSAGES)
@@ -44,7 +45,7 @@ FileInfo::FileInfo(QUrl u, qint64 payloadSize, const QMimeType& mimeType,
 }
 
 FileInfo::FileInfo(QUrl mxcUrl, const QJsonObject& infoJson,
-                   const Omittable<EncryptedFile> &file,
+                   Omittable<EncryptedFile> encryptedFile,
                    QString originalFilename)
     : originalInfoJson(infoJson)
     , mimeType(
@@ -52,7 +53,7 @@ FileInfo::FileInfo(QUrl mxcUrl, const QJsonObject& infoJson,
     , url(move(mxcUrl))
     , payloadSize(fromJson<qint64>(infoJson["size"_ls]))
     , originalName(move(originalFilename))
-    , file(file)
+    , file(move(encryptedFile))
 {
     if(url.isEmpty() && file.has_value()) {
         url = file->url;
@@ -82,15 +83,16 @@ ImageInfo::ImageInfo(const QFileInfo& fi, QSize imageSize)
 {}
 
 ImageInfo::ImageInfo(const QUrl& mxcUrl, qint64 fileSize, const QMimeType& type,
-                     QSize imageSize, const Omittable<EncryptedFile> &file, const QString& originalFilename)
-    : FileInfo(mxcUrl, fileSize, type, file, originalFilename)
+                     QSize imageSize, Omittable<EncryptedFile> encryptedFile,
+                     const QString& originalFilename)
+    : FileInfo(mxcUrl, fileSize, type, move(encryptedFile), originalFilename)
     , imageSize(imageSize)
 {}
 
 ImageInfo::ImageInfo(const QUrl& mxcUrl, const QJsonObject& infoJson,
-                     const Omittable<EncryptedFile> &file,
+                     Omittable<EncryptedFile> encryptedFile,
                      const QString& originalFilename)
-    : FileInfo(mxcUrl, infoJson, file, originalFilename)
+    : FileInfo(mxcUrl, infoJson, move(encryptedFile), originalFilename)
     , imageSize(infoJson["w"_ls].toInt(), infoJson["h"_ls].toInt())
 {}
 
@@ -103,10 +105,10 @@ void ImageInfo::fillInfoJson(QJsonObject* infoJson) const
         infoJson->insert(QStringLiteral("h"), imageSize.height());
 }
 
-Thumbnail::Thumbnail(const QJsonObject& infoJson, const Omittable<EncryptedFile> &file)
+Thumbnail::Thumbnail(const QJsonObject& infoJson,
+                     Omittable<EncryptedFile> encryptedFile)
     : ImageInfo(QUrl(infoJson["thumbnail_url"_ls].toString()),
-                infoJson["thumbnail_info"_ls].toObject(),
-                file)
+                infoJson["thumbnail_info"_ls].toObject(), move(encryptedFile))
 {}
 
 void Thumbnail::fillInfoJson(QJsonObject* infoJson) const
diff --git a/lib/events/eventcontent.h b/lib/events/eventcontent.h
index 76f20f79..4134202a 100644
--- a/lib/events/eventcontent.h
+++ b/lib/events/eventcontent.h
@@ -19,16 +19,13 @@ class QFileInfo;
 
 namespace Quotient {
 namespace EventContent {
-    /**
-     * A base class for all content types that can be stored
-     * in a RoomMessageEvent
-     *
-     * Each content type class should have a constructor taking
-     * a QJsonObject and override fillJson() with an implementation
-     * that will fill the target QJsonObject with stored values. It is
-     * assumed but not required that a content object can also be created
-     * from plain data.
-     */
+    //! \brief Base for all content types that can be stored in RoomMessageEvent
+    //!
+    //! Each content type class should have a constructor taking
+    //! a QJsonObject and override fillJson() with an implementation
+    //! that will fill the target QJsonObject with stored values. It is
+    //! assumed but not required that a content object can also be created
+    //! from plain data.
     class QUOTIENT_API Base {
     public:
         explicit Base(QJsonObject o = {}) : originalJson(std::move(o)) {}
@@ -60,45 +57,55 @@ namespace EventContent {
     //     ImageContent : UrlWithThumbnailContent<ImageInfo>
     //     VideoContent : PlayableContent<UrlWithThumbnailContent<ImageInfo>>
 
-    /**
-     * A base/mixin class for structures representing an "info" object for
-     * some content types. These include most attachment types currently in
-     * the CS API spec.
-     *
-     * In order to use it in a content class, derive both from TypedBase
-     * (or Base) and from FileInfo (or its derivative, such as \p ImageInfo)
-     * and call fillInfoJson() to fill the "info" subobject. Make sure
-     * to pass an "info" part of JSON to FileInfo constructor, not the whole
-     * JSON content, as well as contents of "url" (or a similar key) and
-     * optionally "filename" node from the main JSON content. Assuming you
-     * don't do unusual things, you should use \p UrlBasedContent<> instead
-     * of doing multiple inheritance and overriding Base::fillJson() by hand.
-     *
-     * This class is not polymorphic.
-     */
+    //! \brief Mix-in class representing `info` subobject in content JSON
+    //!
+    //! This is one of base classes for content types that deal with files or
+    //! URLs. It stores the file metadata attributes, such as size, MIME type
+    //! etc. found in the `content/info` subobject of event JSON payloads.
+    //! Actual content classes derive from this class _and_ TypedBase that
+    //! provides a polymorphic interface to access data in the mix-in. FileInfo
+    //! (as well as ImageInfo, that adds image size to the metadata) is NOT
+    //! polymorphic and is used in a non-polymorphic way to store thumbnail
+    //! metadata (in a separate instance), next to the metadata on the file
+    //! itself.
+    //!
+    //! If you need to make a new _content_ (not info) class based on files/URLs
+    //! take UrlBasedContent as the example, i.e.:
+    //! 1. Double-inherit from this class (or ImageInfo) and TypedBase.
+    //! 2. Provide a constructor from QJsonObject that will pass the `info`
+    //!    subobject (not the whole content JSON) down to FileInfo/ImageInfo.
+    //! 3. Override fillJson() to customise the JSON export logic. Make sure
+    //!    to call toInfoJson() from it to produce the payload for the `info`
+    //!    subobject in the JSON payload.
+    //!
+    //! \sa ImageInfo, FileContent, ImageContent, AudioContent, VideoContent,
+    //!     UrlBasedContent
     class QUOTIENT_API FileInfo {
     public:
         FileInfo() = default;
+        //! \brief Construct from a QFileInfo object
+        //!
+        //! \param fi a QFileInfo object referring to an existing file
         explicit FileInfo(const QFileInfo& fi);
         explicit FileInfo(QUrl mxcUrl, qint64 payloadSize = -1,
                           const QMimeType& mimeType = {},
-                          Omittable<EncryptedFile> file = none,
+                          Omittable<EncryptedFile> encryptedFile = none,
                           QString originalFilename = {});
+        //! \brief Construct from a JSON `info` payload
+        //!
+        //! Make sure to pass the `info` subobject of content JSON, not the
+        //! whole JSON content.
         FileInfo(QUrl mxcUrl, const QJsonObject& infoJson,
-                 const Omittable<EncryptedFile> &file,
+                 Omittable<EncryptedFile> encryptedFile,
                  QString originalFilename = {});
 
         bool isValid() const;
 
-        void fillInfoJson(QJsonObject* infoJson) const;
-
-        /**
-         * \brief Extract media id from the URL
-         *
-         * This can be used, e.g., to construct a QML-facing image://
-         * URI as follows:
-         * \code "image://provider/" + info.mediaId() \endcode
-         */
+        //! \brief Extract media id from the URL
+        //!
+        //! This can be used, e.g., to construct a QML-facing image://
+        //! URI as follows:
+        //! \code "image://provider/" + info.mediaId() \endcode
         QString mediaId() const { return url.authority() + url.path(); }
 
     public:
@@ -118,19 +125,17 @@ namespace EventContent {
         return infoJson;
     }
 
-    /**
-     * A content info class for image content types: image, thumbnail, video
-     */
+    //! \brief A content info class for image/video content types and thumbnails
     class QUOTIENT_API ImageInfo : public FileInfo {
     public:
         ImageInfo() = default;
         explicit ImageInfo(const QFileInfo& fi, QSize imageSize = {});
         explicit ImageInfo(const QUrl& mxcUrl, qint64 fileSize = -1,
                            const QMimeType& type = {}, QSize imageSize = {},
-                           const Omittable<EncryptedFile> &file = none,
+                           Omittable<EncryptedFile> encryptedFile = none,
                            const QString& originalFilename = {});
         ImageInfo(const QUrl& mxcUrl, const QJsonObject& infoJson,
-                  const Omittable<EncryptedFile> &encryptedFile,
+                  Omittable<EncryptedFile> encryptedFile,
                   const QString& originalFilename = {});
 
         void fillInfoJson(QJsonObject* infoJson) const;
@@ -139,22 +144,18 @@ namespace EventContent {
         QSize imageSize;
     };
 
-    /**
-     * An auxiliary class for an info type that carries a thumbnail
-     *
-     * This class saves/loads a thumbnail to/from "info" subobject of
-     * the JSON representation of event content; namely,
-     * "info/thumbnail_url" and "info/thumbnail_info" fields are used.
-     */
+    //! \brief An auxiliary class for an info type that carries a thumbnail
+    //!
+    //! This class saves/loads a thumbnail to/from `info` subobject of
+    //! the JSON representation of event content; namely, `info/thumbnail_url`
+    //! and `info/thumbnail_info` fields are used.
     class QUOTIENT_API Thumbnail : public ImageInfo {
     public:
         using ImageInfo::ImageInfo;
-        Thumbnail(const QJsonObject& infoJson, const Omittable<EncryptedFile> &file = none);
+        Thumbnail(const QJsonObject& infoJson,
+                  Omittable<EncryptedFile> encryptedFile = none);
 
-        /**
-         * Writes thumbnail information to "thumbnail_info" subobject
-         * and thumbnail URL to "thumbnail_url" node inside "info".
-         */
+        //! \brief Add thumbnail information to the passed `info` JSON object
         void fillInfoJson(QJsonObject* infoJson) const;
     };
 
@@ -170,18 +171,15 @@ namespace EventContent {
         using Base::Base;
     };
 
-    /**
-     * A base class for content types that have a URL and additional info
-     *
-     * Types that derive from this class template take "url" and,
-     * optionally, "filename" values from the top-level JSON object and
-     * the rest of information from the "info" subobject, as defined by
-     * the parameter type.
-     *
-     * \tparam InfoT base info class
-     */
+    //! \brief A template class for content types with a URL and additional info
+    //!
+    //! Types that derive from this class template take `url` and,
+    //! optionally, `filename` values from the top-level JSON object and
+    //! the rest of information from the `info` subobject, as defined by
+    //! the parameter type.
+    //! \tparam InfoT base info class - FileInfo or ImageInfo
     template <class InfoT>
-    class QUOTIENT_API UrlBasedContent : public TypedBase, public InfoT {
+    class UrlBasedContent : public TypedBase, public InfoT {
     public:
         using InfoT::InfoT;
         explicit UrlBasedContent(const QJsonObject& json)
@@ -241,43 +239,39 @@ namespace EventContent {
         }
     };
 
-    /**
-     * Content class for m.image
-     *
-     * Available fields:
-     * - corresponding to the top-level JSON:
-     *   - url
-     *   - filename (extension to the spec)
-     * - corresponding to the "info" subobject:
-     *   - payloadSize ("size" in JSON)
-     *   - mimeType ("mimetype" in JSON)
-     *   - imageSize (QSize for a combination of "h" and "w" in JSON)
-     *   - thumbnail.url ("thumbnail_url" in JSON)
-     * - corresponding to the "info/thumbnail_info" subobject: contents of
-     *   thumbnail field, in the same vein as for the main image:
-     *   - payloadSize
-     *   - mimeType
-     *   - imageSize
-     */
-    using ImageContent = UrlWithThumbnailContent<ImageInfo>;
-
-    /**
-     * Content class for m.file
-     *
-     * Available fields:
-     * - corresponding to the top-level JSON:
-     *   - url
-     *   - filename
-     * - corresponding to the "info" subobject:
-     *   - payloadSize ("size" in JSON)
-     *   - mimeType ("mimetype" in JSON)
-     *   - thumbnail.url ("thumbnail_url" in JSON)
-     * - corresponding to the "info/thumbnail_info" subobject:
-     *   - thumbnail.payloadSize
-     *   - thumbnail.mimeType
-     *   - thumbnail.imageSize (QSize for "h" and "w" in JSON)
-     */
-    using FileContent = UrlWithThumbnailContent<FileInfo>;
+    //! \brief Content class for m.image
+    //!
+    //! Available fields:
+    //! - corresponding to the top-level JSON:
+    //!   - url
+    //!   - filename (extension to the spec)
+    //! - corresponding to the `info` subobject:
+    //!   - payloadSize (`size` in JSON)
+    //!   - mimeType (`mimetype` in JSON)
+    //!   - imageSize (QSize for a combination of `h` and `w` in JSON)
+    //!   - thumbnail.url (`thumbnail_url` in JSON)
+    //! - corresponding to the `info/thumbnail_info` subobject: contents of
+    //!   thumbnail field, in the same vein as for the main image:
+    //!   - payloadSize
+    //!   - mimeType
+    //!   - imageSize
+    using ImageContent = UrlBasedContent<ImageInfo>;
+
+    //! \brief Content class for m.file
+    //!
+    //! Available fields:
+    //! - corresponding to the top-level JSON:
+    //!   - url
+    //!   - filename
+    //! - corresponding to the `info` subobject:
+    //!   - payloadSize (`size` in JSON)
+    //!   - mimeType (`mimetype` in JSON)
+    //!   - thumbnail.url (`thumbnail_url` in JSON)
+    //! - corresponding to the `info/thumbnail_info` subobject:
+    //!   - thumbnail.payloadSize
+    //!   - thumbnail.mimeType
+    //!   - thumbnail.imageSize (QSize for `h` and `w` in JSON)
+    using FileContent = UrlBasedContent<FileInfo>;
 } // namespace EventContent
 } // namespace Quotient
 Q_DECLARE_METATYPE(const Quotient::EventContent::TypedBase*)