loot/libloot
0
0
Fork 0
mirror of https://github.com/loot/libloot.git synced 2026-07-27 14:16:01 -07:00
Code Issues Packages Projects Releases Wiki Activity

Fix doc comment formatting inconsistencies

Browse Source
This commit is contained in:
Oliver Hamlet
2022-02-06 18:31:42 +00:00
parent d595bcf56e
commit c64039e7e2
4 changed files with 125 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/loot/api.h
+41 -48
View File
@@ -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<void(LogLevel, const char*)> 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<GameInterface> CreateGameHandle(
const GameType game,
include/loot/database_interface.h
+72 -72
View File
@@ -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<std::string> 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<Message> 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<PluginMetadata> 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<PluginMetadata> 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;
include/loot/exception/error_categories.h
+5 -4
View File
@@ -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();
}
include/loot/struct/simple_message.h
+7 -8
View File
@@ -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;
};
}