From c64039e7e2128ba572e696d14d9469f56513c30d Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Sun, 6 Feb 2022 16:39:47 +0000 Subject: [PATCH] Fix doc comment formatting inconsistencies --- include/loot/api.h | 89 ++++++------- include/loot/database_interface.h | 144 +++++++++++----------- include/loot/exception/error_categories.h | 9 +- include/loot/struct/simple_message.h | 15 ++- 4 files changed, 125 insertions(+), 132 deletions(-) diff --git a/include/loot/api.h b/include/loot/api.h index 5501319f..ef8d927d 100644 --- a/include/loot/api.h +++ b/include/loot/api.h @@ -42,13 +42,11 @@ #include "loot/loot_version.h" namespace loot { -/**@}*/ -/**********************************************************************/ /** - * @name - *Logging - *Functions - *************************************************************************/ -/**@{*/ +/** + * @} + * @name Logging Functions + * @{ + */ /** * @brief Set the callback function that is called when logging. @@ -61,56 +59,51 @@ namespace loot { LOOT_API void SetLoggingCallback( std::function callback); -/**@}*/ -/**********************************************************************/ /** - * @name - *Version - *Functions - *************************************************************************/ -/**@{*/ +/** + * @} + * @name Version Functions + * @{ + */ /** - * @brief Checks for API compatibility. - * @details Checks whether the loaded API is compatible with the given - * version of the API, abstracting API stability policy away from - * clients. The version numbering used is major.minor.patch. - * @param major - * The major version number to check. - * @param minor - * The minor version number to check. - * @param patch - * The patch version number to check. - * @returns True if the API versions are compatible, false otherwise. + * @brief Checks for API compatibility. + * @details Checks whether the loaded API is compatible with the given + * version of the API, abstracting API stability policy away from + * clients. The version numbering used is major.minor.patch. + * @param major + * The major version number to check. + * @param minor + * The minor version number to check. + * @param patch + * The patch version number to check. + * @returns True if the API versions are compatible, false otherwise. */ LOOT_API bool IsCompatible(const unsigned int major, const unsigned int minor, const unsigned int patch); -/**@}*/ -/**********************************************************************/ /** - * @name - *Lifecycle - *Management - *Functions - *************************************************************************/ -/**@{*/ +/** + * @} + * @name Lifecycle Management Functions + * @{ + */ /** - * @brief Initialise a new game handle. - * @details Creates a handle for a game, which is then used by all - * game-specific functions. - * @param game - * A game code for which to create the handle. - * @param game_path - * The relative or absolute path to the directory containing the - * game's executable. - * @param game_local_path - * The relative or absolute path to the game's folder in - * `%%LOCALAPPDATA%` or an empty path. If an empty path, the API will - * attempt to look up the path that `%%LOCALAPPDATA%` corresponds to. - * This parameter is provided so that systems lacking that environmental - * variable (eg. Linux) can still use the API. - * @returns The new game handle. + * @brief Initialise a new game handle. + * @details Creates a handle for a game, which is then used by all + * game-specific functions. + * @param game + * A game code for which to create the handle. + * @param game_path + * The relative or absolute path to the directory containing the + * game's executable. + * @param game_local_path + * The relative or absolute path to the game's folder in + * `%%LOCALAPPDATA%` or an empty path. If an empty path, the API will + * attempt to look up the path that `%%LOCALAPPDATA%` corresponds to. + * This parameter is provided so that systems lacking that environmental + * variable (eg. Linux) can still use the API. + * @returns The new game handle. */ LOOT_API std::shared_ptr CreateGameHandle( const GameType game, diff --git a/include/loot/database_interface.h b/include/loot/database_interface.h index f2e9d353..5162124f 100644 --- a/include/loot/database_interface.h +++ b/include/loot/database_interface.h @@ -41,26 +41,26 @@ namespace loot { class DatabaseInterface { public: /** - * @name Data Reading & Writing - * @{ + * @name Data Reading & Writing + * @{ */ /** - * @brief Loads the masterlist, userlist and masterlist prelude from the - * paths specified. - * @details Can be called multiple times, each time replacing the - * previously-loaded data. - * @param masterlist_path - * The relative or absolute path to the masterlist file that should be - * loaded. - * @param userlist_path - * The relative or absolute path to the userlist file that should be - * loaded, or an empty path. If an empty path, no userlist will be - * loaded. - * @param masterlist_prelude_path - * The relative or absolute path to the masterlist prelude file that - * should be loaded. If an empty path, no masterlist prelude will be - * loaded. + * @brief Loads the masterlist, userlist and masterlist prelude from the + * paths specified. + * @details Can be called multiple times, each time replacing the + * previously-loaded data. + * @param masterlist_path + * The relative or absolute path to the masterlist file that should be + * loaded. + * @param userlist_path + * The relative or absolute path to the userlist file that should be + * loaded, or an empty path. If an empty path, no userlist will be + * loaded. + * @param masterlist_prelude_path + * The relative or absolute path to the masterlist prelude file that + * should be loaded. If an empty path, no masterlist prelude will be + * loaded. */ virtual void LoadLists( const std::filesystem::path& masterlist_path, @@ -70,49 +70,49 @@ public: /** * Writes a metadata file containing all loaded user-added metadata. * @param outputFile - * The path to which the file shall be written. + * The path to which the file shall be written. * @param overwrite - * If `false` and `outputFile` already exists, no data will be - * written. Otherwise, data will be written. + * If `false` and `outputFile` already exists, no data will be + * written. Otherwise, data will be written. */ virtual void WriteUserMetadata(const std::filesystem::path& outputFile, const bool overwrite) const = 0; /** - * @brief Writes a minimal metadata file that only contains plugins with - * Bash Tag suggestions and/or dirty info, plus the suggestions and - * info themselves. - * @param outputFile - * The path to which the file shall be written. - * @param overwrite - * If `false` and `outputFile` already exists, no data will be - * written. Otherwise, data will be written. + * @brief Writes a minimal metadata file that only contains plugins with + * Bash Tag suggestions and/or dirty info, plus the suggestions and + * info themselves. + * @param outputFile + * The path to which the file shall be written. + * @param overwrite + * If `false` and `outputFile` already exists, no data will be + * written. Otherwise, data will be written. */ virtual void WriteMinimalList(const std::filesystem::path& outputFile, const bool overwrite) const = 0; /** - * @} - * @name Non-plugin Data Access - * @{ + * @} + * @name Non-plugin Data Access + * @{ */ /** - * @brief Gets the Bash Tags that are listed in the loaded metadata lists. - * @details Bash Tag suggestions can include plugins not in this list. - * @returns A set of Bash Tag names. + * @brief Gets the Bash Tags that are listed in the loaded metadata lists. + * @details Bash Tag suggestions can include plugins not in this list. + * @returns A set of Bash Tag names. */ virtual std::vector GetKnownBashTags() const = 0; /** - * @brief Get all general messages listen in the loaded metadata lists. - * @param evaluateConditions - * If true, any metadata conditions are evaluated before the metadata - * is returned, otherwise unevaluated metadata is returned. Evaluating - * general message conditions also clears the condition cache before - * evaluating conditions. - * @returns A vector of messages supplied in the metadata lists but not - * attached to any particular plugin. + * @brief Get all general messages listen in the loaded metadata lists. + * @param evaluateConditions + * If true, any metadata conditions are evaluated before the metadata + * is returned, otherwise unevaluated metadata is returned. Evaluating + * general message conditions also clears the condition cache before + * evaluating conditions. + * @returns A vector of messages supplied in the metadata lists but not + * attached to any particular plugin. */ virtual std::vector GetGeneralMessages( bool evaluateConditions = false) const = 0; @@ -164,25 +164,25 @@ public: const std::string& toGroupName) const = 0; /** - * @} - * @name Plugin Data Access - * @{ + * @} + * @name Plugin Data Access + * @{ */ /** - * @brief Get all a plugin's loaded metadata. - * @param plugin - * The filename of the plugin to look up metadata for. - * @param includeUserMetadata - * If true, any user metadata the plugin has is included in the - * returned metadata, otherwise the metadata returned only includes - * metadata from the masterlist. - * @param evaluateConditions - * If true, any metadata conditions are evaluated before the metadata - * is returned, otherwise unevaluated metadata is returned. Evaluating - * plugin metadata conditions does not clear the condition cache. - * @returns If the plugin has metadata, an optional containing that metadata, - * otherwise an optional containing no value. + * @brief Get all a plugin's loaded metadata. + * @param plugin + * The filename of the plugin to look up metadata for. + * @param includeUserMetadata + * If true, any user metadata the plugin has is included in the + * returned metadata, otherwise the metadata returned only includes + * metadata from the masterlist. + * @param evaluateConditions + * If true, any metadata conditions are evaluated before the metadata + * is returned, otherwise unevaluated metadata is returned. Evaluating + * plugin metadata conditions does not clear the condition cache. + * @returns If the plugin has metadata, an optional containing that metadata, + * otherwise an optional containing no value. */ virtual std::optional GetPluginMetadata( const std::string& plugin, @@ -190,26 +190,26 @@ public: bool evaluateConditions = false) const = 0; /** - * @brief Get a plugin's metadata loaded from the given userlist. - * @param plugin - * The filename of the plugin to look up user-added metadata for. - * @param evaluateConditions - * If true, any metadata conditions are evaluated before the metadata - * is returned, otherwise unevaluated metadata is returned. Evaluating - * plugin metadata conditions does not clear the condition cache. - * @returns If the plugin has user-added metadata, an optional containing - * that metadata, otherwise an optional containing no value. + * @brief Get a plugin's metadata loaded from the given userlist. + * @param plugin + * The filename of the plugin to look up user-added metadata for. + * @param evaluateConditions + * If true, any metadata conditions are evaluated before the metadata + * is returned, otherwise unevaluated metadata is returned. Evaluating + * plugin metadata conditions does not clear the condition cache. + * @returns If the plugin has user-added metadata, an optional containing + * that metadata, otherwise an optional containing no value. */ virtual std::optional GetPluginUserMetadata( const std::string& plugin, bool evaluateConditions = false) const = 0; /** - * @brief Sets a plugin's user metadata, overwriting any existing user - * metadata. - * @param pluginMetadata - * The user metadata you want to set, with plugin.Name() being the - * filename of the plugin the metadata is for. + * @brief Sets a plugin's user metadata, overwriting any existing user + * metadata. + * @param pluginMetadata + * The user metadata you want to set, with plugin.Name() being the + * filename of the plugin the metadata is for. */ virtual void SetPluginUserMetadata(const PluginMetadata& pluginMetadata) = 0; diff --git a/include/loot/exception/error_categories.h b/include/loot/exception/error_categories.h index 5e4f0bba..3b7d6c41 100644 --- a/include/loot/exception/error_categories.h +++ b/include/loot/exception/error_categories.h @@ -30,10 +30,11 @@ #include "loot/api_decorator.h" namespace loot { -/** @brief Get the error category that can be used to identify system_error - * exceptions that are due to libloadorder errors. - * @returns A reference to the static object of unspecified runtime type, - derived from std::error_category. +/** + * @brief Get the error category that can be used to identify system_error + * exceptions that are due to libloadorder errors. + * @returns A reference to the static object of unspecified runtime type, + * derived from std::error_category. */ LOOT_API const std::error_category& libloadorder_category(); } diff --git a/include/loot/struct/simple_message.h b/include/loot/struct/simple_message.h index b3419eb6..dde52ab9 100644 --- a/include/loot/struct/simple_message.h +++ b/include/loot/struct/simple_message.h @@ -29,21 +29,20 @@ #include "loot/enum/message_type.h" namespace loot { -/** @brief A structure that holds the type of a message and the message string - * itself. */ +/** + * A structure that holds the type of a message and the message string itself. + */ struct SimpleMessage { - /** @brief The type of the message. */ + /** The type of the message. */ MessageType type; - /** @brief The language the message string is written in. */ + /** The language the message string is written in. */ std::string language; - /** - * @brief The message string, which may be formatted using CommonMark. - */ + /** The message string, which may be formatted using CommonMark. */ std::string text; - /** @brief The message's condition string. */ + /** The message's condition string. */ std::string condition; }; }