From 43e03d13f370af2135dcc790aca8320a34ff1c77 Mon Sep 17 00:00:00 2001 From: jothepro Date: Mon, 13 Dec 2021 23:08:02 +0100 Subject: [PATCH] minor code cleanup - fix, remove, add and edit comments - enable UML_LOOK in Doxygen --- Doxyfile | 2 +- README.md | 2 +- lib/include/CloudSync/BasicCredentials.hpp | 4 +--- lib/include/CloudSync/Cloud.hpp | 4 ++-- lib/include/CloudSync/CloudFactory.hpp | 9 +++------ lib/include/CloudSync/Directory.hpp | 13 +++++++------ lib/include/CloudSync/File.hpp | 18 ++++++++++++++---- lib/include/CloudSync/OAuth2Credentials.hpp | 1 + lib/include/CloudSync/Resource.hpp | 6 +++--- lib/src/CloudImpl.hpp | 2 +- lib/src/dropbox/DropboxCloud.hpp | 2 +- lib/src/dropbox/DropboxDirectory.hpp | 2 +- lib/src/dropbox/DropboxFile.hpp | 2 +- lib/src/gdrive/GDriveCloud.hpp | 2 +- lib/src/gdrive/GDriveDirectory.hpp | 2 +- lib/src/gdrive/GDriveFile.hpp | 2 +- lib/src/nextcloud/NextcloudCloud.hpp | 2 +- 17 files changed, 41 insertions(+), 34 deletions(-) diff --git a/Doxyfile b/Doxyfile index 3be76b5..49d28e0 100644 --- a/Doxyfile +++ b/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 diff --git a/README.md b/README.md index 7bc1185..f342d56 100644 --- a/README.md +++ b/README.md @@ -211,6 +211,6 @@ In your Nextcloud installation go to settings > user > 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; diff --git a/lib/include/CloudSync/Cloud.hpp b/lib/include/CloudSync/Cloud.hpp index f2333d7..d3af938 100644 --- a/lib/include/CloudSync/Cloud.hpp +++ b/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 +} diff --git a/lib/include/CloudSync/CloudFactory.hpp b/lib/include/CloudSync/CloudFactory.hpp index c3aef49..1ef6c3e 100644 --- a/lib/include/CloudSync/CloudFactory.hpp +++ b/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 m_request; }; -} // namespace CloudSync +} diff --git a/lib/include/CloudSync/Directory.hpp b/lib/include/CloudSync/Directory.hpp index 812deba..4492f4c 100644 --- a/lib/include/CloudSync/Directory.hpp +++ b/lib/include/CloudSync/Directory.hpp @@ -2,13 +2,14 @@ #include "File.hpp" #include "Resource.hpp" -#include 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 get_file(const std::filesystem::path &path) const = 0; }; -} // namespace CloudSync +} diff --git a/lib/include/CloudSync/File.hpp b/lib/include/CloudSync/File.hpp index d8b7f72..a13f20e 100644 --- a/lib/include/CloudSync/File.hpp +++ b/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 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& content) = 0; /** @@ -34,4 +44,4 @@ namespace CloudSync { */ virtual bool poll_change() = 0; }; -} // namespace CloudSync +} diff --git a/lib/include/CloudSync/OAuth2Credentials.hpp b/lib/include/CloudSync/OAuth2Credentials.hpp index 7ace528..30e3d99 100644 --- a/lib/include/CloudSync/OAuth2Credentials.hpp +++ b/lib/include/CloudSync/OAuth2Credentials.hpp @@ -6,6 +6,7 @@ #include namespace CloudSync { + /// OAuth2 credentials for authorization at Dropbox, GDrive, OneDrive class OAuth2Credentials { public: virtual ~OAuth2Credentials() = default; diff --git a/lib/include/CloudSync/Resource.hpp b/lib/include/CloudSync/Resource.hpp index 213bcae..da60c12 100644 --- a/lib/include/CloudSync/Resource.hpp +++ b/lib/include/CloudSync/Resource.hpp @@ -7,6 +7,7 @@ #include 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; diff --git a/lib/src/CloudImpl.hpp b/lib/src/CloudImpl.hpp index 74c6ae9..90eea9b 100644 --- a/lib/src/CloudImpl.hpp +++ b/lib/src/CloudImpl.hpp @@ -18,4 +18,4 @@ namespace CloudSync { std::shared_ptr m_request; std::string m_base_url; }; -} // namespace CloudSync +} diff --git a/lib/src/dropbox/DropboxCloud.hpp b/lib/src/dropbox/DropboxCloud.hpp index 328d4c2..a2602b1 100644 --- a/lib/src/dropbox/DropboxCloud.hpp +++ b/lib/src/dropbox/DropboxCloud.hpp @@ -22,4 +22,4 @@ namespace CloudSync::dropbox { void logout() override; }; -} // namespace CloudSync::dropbox +} diff --git a/lib/src/dropbox/DropboxDirectory.hpp b/lib/src/dropbox/DropboxDirectory.hpp index 0768ca1..a3b8612 100644 --- a/lib/src/dropbox/DropboxDirectory.hpp +++ b/lib/src/dropbox/DropboxDirectory.hpp @@ -40,4 +40,4 @@ namespace CloudSync::dropbox { */ std::shared_ptr parseEntry(const json &entry, const std::string &resourceTypeFallback = "") const; }; -} // namespace CloudSync::dropbox +} diff --git a/lib/src/dropbox/DropboxFile.hpp b/lib/src/dropbox/DropboxFile.hpp index ae01d8c..21cda18 100644 --- a/lib/src/dropbox/DropboxFile.hpp +++ b/lib/src/dropbox/DropboxFile.hpp @@ -27,4 +27,4 @@ namespace CloudSync::dropbox { std::shared_ptr prepare_read_request() const; std::shared_ptr prepare_write_request() const; }; -} // namespace CloudSync::dropbox +} diff --git a/lib/src/gdrive/GDriveCloud.hpp b/lib/src/gdrive/GDriveCloud.hpp index c1e1a94..6d6977e 100644 --- a/lib/src/gdrive/GDriveCloud.hpp +++ b/lib/src/gdrive/GDriveCloud.hpp @@ -34,4 +34,4 @@ namespace CloudSync::gdrive { private: std::string m_root_name; }; -} // namespace CloudSync::gdrive +} diff --git a/lib/src/gdrive/GDriveDirectory.hpp b/lib/src/gdrive/GDriveDirectory.hpp index 6d4c9e6..ec7e9ff 100644 --- a/lib/src/gdrive/GDriveDirectory.hpp +++ b/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 +} diff --git a/lib/src/gdrive/GDriveFile.hpp b/lib/src/gdrive/GDriveFile.hpp index b43f218..4f2ec58 100644 --- a/lib/src/gdrive/GDriveFile.hpp +++ b/lib/src/gdrive/GDriveFile.hpp @@ -33,4 +33,4 @@ namespace CloudSync::gdrive { std::shared_ptr prepare_read_request() const; std::shared_ptr prepare_write_request() const; }; -} // namespace CloudSync::gdrive +} diff --git a/lib/src/nextcloud/NextcloudCloud.hpp b/lib/src/nextcloud/NextcloudCloud.hpp index 542e335..6b858c1 100644 --- a/lib/src/nextcloud/NextcloudCloud.hpp +++ b/lib/src/nextcloud/NextcloudCloud.hpp @@ -28,4 +28,4 @@ namespace CloudSync::nextcloud { void logout() override; }; -} // namespace CloudSync::nextcloud +}