minor code cleanup

- fix, remove, add and edit comments
- enable UML_LOOK in Doxygen

Doxyfile

@@ -2431,7 +2431,7 @@ GROUP_GRAPHS           = YES
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-UML_LOOK               = NO
+UML_LOOK               = YES
 
 # If the UML_LOOK tag is enabled, the fields and methods are shown inside the
 # class node. If there are many fields or methods and many nodes the graph may

README.md

@@ -211,6 +211,6 @@ In your Nextcloud installation go to <kbd>settings</kbd> >  <kbd>user</kbd> > <k
 
 - Implement equality operators for Cloud, Directory, File
 - Add tests for CURL wrapper (e.g. by going against a (mocked?) http server)
-- implementing support for big file upload/download (chunked upload/download
+- implementing support for big file upload/download (chunked upload/download)
 - Improve integration-test coverage
 - Improve unit-test coverage

lib/include/CloudSync/BasicCredentials.hpp

@@ -4,9 +4,7 @@
 #include <memory>
 
 namespace CloudSync {
-    /**
-     * @brief Basic access authentication credentials. Used for authorization in webdav & nextcloud.
-     */
+    /// Basic access authentication credentials for authorization in WebDav & Nextcloud.
     class BasicCredentials {
     public:
         virtual ~BasicCredentials() = default;

lib/include/CloudSync/Cloud.hpp

@@ -3,7 +3,7 @@
 #include "Directory.hpp"
 
 namespace CloudSync {
-
+    /// Provider-independent representation of the connected cloud.
     class Cloud {
     public:
 
@@ -55,4 +55,4 @@ namespace CloudSync {
         virtual void logout() = 0;
     };
 
-} // namespace CloudSync
+}

lib/include/CloudSync/CloudFactory.hpp

@@ -4,15 +4,12 @@
 #include "OAuth2Credentials.hpp"
 #include "BasicCredentials.hpp"
 
-
-
 namespace CloudSync {
     namespace request {
         class Request;
     }
-    /**
-     * @brief Entrypoint to the library: Create any cloud instance from a given configuration.
-     */
+
+    /// Entrypoint to the library: Create any cloud instance from a given configuration.
     class CloudFactory {
     public:
         CloudFactory();
@@ -102,4 +99,4 @@ namespace CloudSync {
         std::shared_ptr<request::Request> m_request;
     };
 
-} // namespace CloudSync
+}

lib/include/CloudSync/Directory.hpp

@@ -2,13 +2,14 @@
 
 #include "File.hpp"
 #include "Resource.hpp"
-#include <vector>
 
 namespace CloudSync {
-/**
- * Provider-independent representation of a directory. Can be seen as a pointer to the actual folder in the cloud. This
- * does not hold the contents of the folder in memory but makes a network call each time you ask for a resource.
- */
+    /**
+     * @brief Provider-independent representation of a directory.
+     *
+     * Can be seen as a pointer to the actual folder in the cloud. This
+     * does not hold the contents of the folder in memory but makes a network call each time you ask for a resource.
+     */
     class Directory : public Resource {
     public:
         /**
@@ -57,4 +58,4 @@ namespace CloudSync {
          */
         virtual std::shared_ptr<File> get_file(const std::filesystem::path &path) const = 0;
     };
-} // namespace CloudSync
+}

lib/include/CloudSync/File.hpp

@@ -3,6 +3,13 @@
 #include "Resource.hpp"
 
 namespace CloudSync {
+    /**
+     * @brief Provider-independent representation of a file.
+     *
+     * Can be seen as a pointer to the actual file in the cloud. This
+     * does not hold the content of the file in memory but makes a network
+     * call each time you read the file.
+     */
     class File : public Resource {
     public:
 
@@ -13,19 +20,22 @@ namespace CloudSync {
          */
         [[nodiscard]] virtual std::string revision() const = 0;
 
-        /**
-         * @return the file content as a string.
-         */
+        /// Read the content of the file into a string.
         [[nodiscard]] virtual std::string read() const = 0;
+
+        /// Read the content of the file into a binary data-structure.
         [[nodiscard]] virtual std::vector<std::uint8_t> read_binary() const = 0;
 
         /**
+         * @brief Write the content of the file from a string.
          * @throws Resource::ResourceHasChanged if the file has changed on the server. Check for a new file version with
          * `poll_change()` to resolve this exception.
          * @param content New content that should be written to the file. Overrides the existing file content. This may also
          * be binary data.
          */
         virtual void write(const std::string& content) = 0;
+
+        /// Write the content of the file from a binary data-structure.
         virtual void write_binary(const std::vector<std::uint8_t>& content) = 0;
 
         /**
@@ -34,4 +44,4 @@ namespace CloudSync {
          */
         virtual bool poll_change() = 0;
     };
-} // namespace CloudSync
+}

lib/include/CloudSync/OAuth2Credentials.hpp

@@ -6,6 +6,7 @@
 #include <functional>
 
 namespace CloudSync {
+    /// OAuth2 credentials for authorization at Dropbox, GDrive, OneDrive
     class OAuth2Credentials {
     public:
         virtual ~OAuth2Credentials() = default;

lib/include/CloudSync/Resource.hpp

@@ -7,6 +7,7 @@
 #include <vector>
 
 namespace CloudSync {
+    /// Common interface for both directories and files
     class Resource {
     public:
 
@@ -23,9 +24,8 @@ namespace CloudSync {
          * @note Be aware that deletion a file doesn't always mean it's gone. Most clouds know the concept of a
          * recycle bin and will move deleted resources there.
          *
-         * @bug If a directory cannot be removed because it still contains resources, this fails with an undefined behaviour.
-         *      It may for example throw a Cloud::CommunicationError.
-         *      [Help me to improve this](https://gitlab.com/jothepro/libcloudsync)
+         * @bug If a directory cannot be removed because it still contains resources, this may fail for some cloud providers.
+         *      [Help me to improve this](https://github.com/jothepro/libCloudSync)
          */
         virtual void remove() = 0;
 

lib/src/CloudImpl.hpp

@@ -18,4 +18,4 @@ namespace CloudSync {
         std::shared_ptr<request::Request> m_request;
         std::string m_base_url;
     };
-} // namespace CloudSync
+}

lib/src/dropbox/DropboxCloud.hpp

@@ -22,4 +22,4 @@ namespace CloudSync::dropbox {
 
         void logout() override;
     };
-} // namespace CloudSync::dropbox
+}

lib/src/dropbox/DropboxDirectory.hpp

@@ -40,4 +40,4 @@ namespace CloudSync::dropbox {
          */
         std::shared_ptr<Resource> parseEntry(const json &entry, const std::string &resourceTypeFallback = "") const;
     };
-} // namespace CloudSync::dropbox
+}

lib/src/dropbox/DropboxFile.hpp

@@ -27,4 +27,4 @@ namespace CloudSync::dropbox {
         std::shared_ptr<request::Request> prepare_read_request() const;
         std::shared_ptr<request::Request> prepare_write_request() const;
     };
-} // namespace CloudSync::dropbox
+}

lib/src/gdrive/GDriveCloud.hpp

@@ -34,4 +34,4 @@ namespace CloudSync::gdrive {
     private:
         std::string m_root_name;
     };
-} // namespace CloudSync::gdrive
+}

lib/src/gdrive/GDriveDirectory.hpp

@@ -54,4 +54,4 @@ class GDriveDirectory : public OAuthDirectoryImpl {
 
         bool child_resource_exists(const std::string & resource_name) const;
     };
-} // namespace CloudSync::gdrive
+}

lib/src/gdrive/GDriveFile.hpp

@@ -33,4 +33,4 @@ namespace CloudSync::gdrive {
         std::shared_ptr<request::Request> prepare_read_request() const;
         std::shared_ptr<request::Request> prepare_write_request() const;
     };
-} // namespace CloudSync::gdrive
+}

lib/src/nextcloud/NextcloudCloud.hpp

@@ -28,4 +28,4 @@ namespace CloudSync::nextcloud {
 
         void logout() override;
     };
-} // namespace CloudSync::nextcloud
+}