github/azure-sdk-for-cpp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Documentation updates (#2277)

Browse Source
This commit is contained in:
Rick Winter 2021-05-17 16:59:47 -07:00 committed by GitHub
parent e4a18b5eb3
commit 8c5a885299
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 113 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
sdk/core/azure-core/inc/azure/core/context.hpp
View File

@ -22,13 +22,13 @@
namespace Azure { namespace Core {
/**
* @brief An exception that gets thrown when some operation is cancelled.
* @brief An exception thrown when an operation is cancelled.
*
*/
class OperationCancelledException final : public std::runtime_error {
public:
/**
* @brief Construct with message string as description.
* @brief Constructs an `OperationCancelledException` with message string as the description.
*
* @param message The description for the exception.
*/
@ -44,20 +44,34 @@ namespace Azure { namespace Core {
class Context final {
public:
/**
* @brief A context key.
* @brief A key used to store and retrieve data in an #Azure::Core::Context object.
*
*/
class Key final {
Key const* m_uniqueAddress;
public:
/**
* @brief Constructs a `Key`.
*
*/
Key() : m_uniqueAddress(this) {}
/**
* @brief Compares with \p other `Azure::Core::Context::Key` for equality.
* @param other Other `Azure::Core::Context::Key` to compare with.
* @return `true` if instances are equal; otherwise, `false`.
*/
bool operator==(Key const& other) const
{
return this->m_uniqueAddress == other.m_uniqueAddress;
}
/**
* @brief Compares with \p other `Azure::Core::Context::Key` for equality.
* @param other Other `Azure::Core::Context::Key` to compare with.
* @return `false` if instances are equal; otherwise, `true`.
*/
bool operator!=(Key const& other) const { return !(*this == other); }
};
@ -115,7 +129,7 @@ namespace Azure { namespace Core {
public:
/**
* @brief Construct a new context with no deadline, and no value associated.
* @brief Constructs a new context with no deadline, and no value associated.
*
*/
Context() : m_contextSharedState(std::make_shared<ContextSharedState>()) {}
@ -127,7 +141,7 @@ namespace Azure { namespace Core {
Context& operator=(const Context&) = default;
/**
* @brief Create a context with a deadline.
* @brief Creates a context with a deadline.
*
* @param deadline A point in time after which a context expires.
*
@ -139,7 +153,7 @@ namespace Azure { namespace Core {
}
/**
* @brief Create a context without a deadline, but with \p key and \p value associated with it.
* @brief Creates a context without a deadline, but with \p key and \p value associated with it.
*
* @tparam T The type of the value to be stored with the key.
* @param key A key to associate with this context.
@ -154,16 +168,17 @@ namespace Azure { namespace Core {
}
/**
* @brief Get a deadline associated with this context or the branch of contexts this context
* @brief Gets the deadline for this context or the branch of contexts this context
* belongs to.
*
* @return A deadline associated with the context found; `Azure::DateTime::max()` value if a
* specific value can't be found.
* @return The deadline associated with the context; `Azure::DateTime::max()` if no deadline is
* specified.
*
*/
DateTime GetDeadline() const;
/**
* @brief Try to get a value associated with a \p key parameter within this context or the
* @brief Gets the value associated with a \p key parameter within this context or the
* branch of contexts this context belongs to.
*
* @tparam T The type of the value to be retrieved.
@ -171,10 +186,10 @@ namespace Azure { namespace Core {
* @param outputValue A reference to the value corresponding to the \p key to be set, if found
* within the context tree.
*
* @return If found, returns `true`, with \p outputValue set to the value associated with the
* key found; otherwise returns `false`.
* @return `true` if \p key is found, with \p outputValue set to the value associated with the
* key found; otherwise, `false`.
*
* @remark The \p outputValue is left unmodified it the \p key is not found.
* @note The \p outputValue is left unmodified if the \p key is not found.
*/
template <class T> bool TryGetValue(Key const& key, T& outputValue) const
{
@ -204,12 +219,13 @@ namespace Azure { namespace Core {
/**
* @brief Checks if the context is cancelled.
* @return `true` if this context is cancelled, `false` otherwise.
* @return `true` if this context is cancelled; otherwise, `false`.
*/
bool IsCancelled() const noexcept { return GetDeadline() < std::chrono::system_clock::now(); }
/**
* @brief Throws an exception if the context is cancelled.
* @brief Checks if the context is cancelled.
* @throw #Azure::Core::OperationCancelledException if the context is cancelled.
*
*/
void ThrowIfCancelled() const

12
sdk/core/azure-core/inc/azure/core/exception.hpp
View File

@ -66,10 +66,10 @@ namespace Azure { namespace Core {
std::unique_ptr<Azure::Core::Http::RawResponse> RawResponse;
/**
* @brief Construct a new Request Failed Exception object.
* @brief Constructs a new `RequestFailedException` object.
*
* @remark An Exception without an HTTP raw response represent an exception happend
* before sending the request to the server. There is no response yet.
* @note An Exception without an HTTP raw response represents an exception that happened
* before sending the request to the server.
*
* @param message The error description.
*/
@ -79,12 +79,12 @@ namespace Azure { namespace Core {
}
/**
* @brief Construct a new Request Failed Exception object with an HTTP raw response.
* @brief Constructs a new `RequestFailedException` object with an HTTP raw response.
*
* @remark The HTTP raw response is parsed to get the always expected information for all Azure
* @note The HTTP raw response is parsed to populate information expected from all Azure
* Services like the status code, reason phrase and some headers like the request ID. A concrete
* Service exception which derives from this exception uses its constructor to parse the HTTP
* raw response and assing the service specific values to the exception.
* raw response adding the service specific values to the exception.
*
* @param message The error description.
* @param rawResponse The HTTP raw response from the service.

4
sdk/core/azure-core/inc/azure/core/match_conditions.hpp
View File

@ -20,6 +20,10 @@ namespace Azure {
*/
struct MatchConditions
{
/**
* @brief Destructs the `MatchConditions`.
*
*/
virtual ~MatchConditions() = default;
/**

35
sdk/core/azure-core/inc/azure/core/operation.hpp
View File

@ -72,17 +72,21 @@ namespace Azure { namespace Core {
}
public:
/**
* @brief Destructs the `Operation`.
*
*/
virtual ~Operation() {}
/**
* @brief Final result of the long-running operation.
*
* @return Response<T> the final result of the long-running operation.
* @return The final result of the long-running operation.
*/
virtual T Value() const = 0;
/**
* @brief Gets an token representing the operation that can be used to poll for the status of
* @brief Gets a token representing the operation that can be used to poll for the status of
* the long-running operation.
*
* @return std::string The resume token.
@ -90,7 +94,7 @@ namespace Azure { namespace Core {
virtual std::string GetResumeToken() const = 0;
/**
* @brief Get the raw HTTP response.
* @brief Gets the raw HTTP response.
* @return A reference to an #Azure::Core::Http::RawResponse.
* @note Does not give up ownership of the RawResponse.
*/
@ -104,15 +108,15 @@ namespace Azure { namespace Core {
};
/**
* @brief Returns the current #Azure::Core::OperationStatus of the long-running operation.
* @brief Gets the current #Azure::Core::OperationStatus of the long-running operation.
*
*/
OperationStatus Status() const noexcept { return m_status; }
/**
* @brief Returns true if the long-running operation completed.
* @brief Checks if the long-running operation is completed.
*
* @return `true` if the long-running operation is done. `false` otherwise.
* @return `true` if the long-running operation is done, otherwise `false`.
*/
bool IsDone() const noexcept
{
@ -122,15 +126,16 @@ namespace Azure { namespace Core {
}
/**
* @brief Returns true if the long-running operation completed successfully and has produced a
* final result. The final result is accessible from Value().
* @brief Checks if the long-running operation completed successfully and has produced a
* final result.
* @note The final result is accessible from `Value()`.
*
* @return `true` if the long-running operation completed successfully. `false` otherwise.
* @return `true` if the long-running operation completed successfully; otherwise, `false`.
*/
bool HasValue() const noexcept { return (m_status == OperationStatus::Succeeded); }
/**
* @brief Calls the server to get updated status of the long-running operation.
* @brief Gets updated status of the long-running operation.
*
* @return An HTTP #Azure::Core::Http::RawResponse returned from the service.
*/
@ -142,9 +147,9 @@ namespace Azure { namespace Core {
}
/**
* @brief Calls the server to get updated status of the long-running operation.
* @brief Gets updated status of the long-running operation.
*
* @param context #Azure::Core::Context allows the user to cancel the long-running operation.
* @param context #Azure::Core::Context allows canceling of the long-running operation.
*
* @return An HTTP #Azure::Core::Http::RawResponse returned from the service.
*/
@ -156,7 +161,7 @@ namespace Azure { namespace Core {
}
/**
* @brief Periodically calls the server till the long-running operation completes.
* @brief Periodically polls till the long-running operation completes.
*
* @param period Time in milliseconds to wait between polls.
*
@ -170,10 +175,10 @@ namespace Azure { namespace Core {
}
/**
* @brief Periodically calls the server till the long-running operation completes;
* @brief Periodically polls till the long-running operation completes;
*
* @param period Time in milliseconds to wait between polls.
* @param context #Azure::Core::Context allows the user to cancel the long-running operation.
* @param context #Azure::Core::Context allows canceling of the long-running operation.
*
* @return Response<T> the final result of the long-running operation.
*/

20
sdk/core/azure-core/inc/azure/core/operation_status.hpp
View File

@ -27,30 +27,30 @@ namespace Azure { namespace Core {
public:
/**
* @brief Construct an #Azure::Core::OperationStatus with \p value.
* @brief Constructs an `OperationStatus` with \p value.
*
* @param value The value to initialize with.
*/
explicit OperationStatus(const std::string& value) : m_value(value) {}
/**
* @brief Construct an #Azure::Core::OperationStatus with \p value.
* @brief Constructs an `OperationStatus` with \p value.
*
* @param value The value to initialize with.
*/
explicit OperationStatus(std::string&& value) : m_value(std::move(value)) {}
/**
* @brief Construct an #Azure::Core::OperationStatus with \p value.
* @brief Constructs an `OperationStatus` with \p value.
*
* @param value The value to initialize with.
*/
explicit OperationStatus(const char* value) : m_value(value) {}
/**
* @brief Compare two #Azure::Core::OperationStatus objects for equality.
* @brief Compares two `OperationStatus` objects for equality.
*
* @param other An #Azure::Core::OperationStatus to compare with.
* @param other An `OperationStatus` to compare with.
*
* @return `true` if the states have the same string representation. `false` otherwise.
* @return `true` if the states have the same string representation; otherwise,`false`.
*/
bool operator==(const OperationStatus& other) const noexcept
{
@ -59,16 +59,16 @@ namespace Azure { namespace Core {
}
/**
* @brief Compare two #Azure::Core::OperationStatus objects for equality.
* @brief Compares two `OperationStatus` objects for equality.
*
* @param other A #Azure::Core::OperationStatus to compare with.
* @param other A `OperationStatus` to compare with.
*
* @return `false` if the states have the same string representation. `true` otherwise.
* @return `false` if the states have the same string representation; otherwise, `true`.
*/
bool operator!=(const OperationStatus& other) const noexcept { return !(*this == other); }
/**
* @brief The `std::string` representation of the operation status.
* @brief Gets the `std::string` representation of the operation status.
*
*/
const std::string& Get() const noexcept { return m_value; }

25
sdk/core/azure-core/inc/azure/core/paged_response.hpp
View File

@ -3,7 +3,7 @@
/**
* @file
* @brief Provides support for responses of paginated collections from the service.
* @brief Responses of paginated collections from the service.
*/
#pragma once
@ -18,7 +18,7 @@
namespace Azure { namespace Core {
/**
* @brief Defines the base type and behavior for a paged response.
* @brief The base type and behavior for a paged response.
*
* @remark The template is used for static-inheritance.
*
@ -41,23 +41,23 @@ namespace Azure { namespace Core {
public:
/**
* @brief Destructor.
* @brief Destructs `PagedResponse`.
*
*/
virtual ~PagedResponse() = default;
/**
* @brief Defines the token used to fetch the current page.
* @brief The token used to fetch the current page.
*
*/
std::string CurrentPageToken;
/**
* @brief Defines the token for getting the next page.
* @brief The token for getting the next page.
*
* @remark If there are no more pages, this field becomes an empty string.
* @note If there are no more pages, this field becomes an empty string.
*
* @remark Assumes all services will include NextPageToken in the payload, it is set to either
* @note Assumes all services will include NextPageToken in the payload, it is set to either
* null or empty for the last page or to a value used for getting the next page.
*
*/
@ -70,17 +70,20 @@ namespace Azure { namespace Core {
std::unique_ptr<Azure::Core::Http::RawResponse> RawResponse;
/**
* @brief Check if a page exists. It returns false after the last page.
* @brief Checks if a page exists.
*
* @note Returns false after the last page.
* @return `true` if there are additional pages; otherwise, `false`.
*
*/
bool HasPage() const { return m_hasPage; }
/**
* @brief Move to the next page of the response.
* @brief Moves to the next page of the response.
*
* @remark Calling this method on the last page will set #HasPage() to false.
* @note Calling this method on the last page will set #HasPage() to `false`.
*
* @param context An #Azure::Core::Context controlling the request lifetime.
* @param context An #Azure::Core::Context which can be used to cancel the operation.
*/
void MoveToNextPage(const Azure::Core::Context& context = Azure::Core::Context())
{

2
sdk/core/azure-core/inc/azure/core/platform.hpp
View File

@ -3,7 +3,7 @@
/**
* @file
* @brief Defines platform-specific macros.
* @brief Platform-specific macros.
*/
// The proper way to check for "UWP/NOT UWP" (*):

47
sdk/core/azure-core/inc/azure/core/url.hpp
View File

@ -3,7 +3,7 @@
/**
* @file
* @brief Define an Uniform Resource Location (URL).
* @brief Uniform Resource Locator (URL).
*/
#pragma once
@ -39,7 +39,7 @@ namespace Azure { namespace Core {
} // namespace _detail
/**
* @brief Url represents the location where a request will be performed.
* @brief Represents the location where a request will be performed.
* It can be parsed and initialized from a string that contains all URL components (scheme, host,
* path, etc.). Authority is not currently supported.
*/
@ -62,7 +62,7 @@ namespace Azure { namespace Core {
* @brief Finds the first '?' symbol and parses everything after it as query parameters.
* separated by '&'.
*
* @param encodedQueryParameters String containing one or more query parameters.
* @param encodedQueryParameters `std::string` containing one or more query parameters.
*/
void AppendQueryParameters(const std::string& encodedQueryParameters);
@ -71,14 +71,14 @@ namespace Azure { namespace Core {
* @brief Decodes \p value by transforming all escaped characters to it's non-encoded value.
*
* @param value URL-encoded string.
* @return std::string with non-URL encoded values.
* @return `std::string` with non-URL encoded values.
*/
static std::string Decode(const std::string& value);
/**
* @brief Encodes \p value by escaping characters to the form of %HH where HH are hex digits.
*
* @remark \p doNotEncodeSymbols arg can be used to explicitly ask this function to skip
* @note \p doNotEncodeSymbols arg can be used to explicitly ask this function to skip
* characters from encoding. For instance, using this `= -` input would prevent encoding `=`, `
* ` and `-`.
*
@ -95,9 +95,10 @@ namespace Azure { namespace Core {
Url() {}
/**
* @brief Construct a URL from a URL-encoded string.
* @brief Constructs a URL from a URL-encoded string.
*
* @param encodedUrl URL string that has all its expected parts already URL-encoded.
* @param encodedUrl A URL-encoded string.
* @note encodedUrl is expected to have all parts URL-encoded.
*/
explicit Url(const std::string& encodedUrl);
@ -105,37 +106,37 @@ namespace Azure { namespace Core {
/******** API for building Url from scratch. Override state ********/
/**
* @brief Set URL scheme.
* @brief Sets URL scheme.
*
* @param scheme URL scheme.
*/
void SetScheme(const std::string& scheme) { m_scheme = scheme; }
/**
* @brief Set URL host.
* @brief Sets URL host.
*
* @param host URL host.
*/
void SetHost(const std::string& encodedHost) { m_host = encodedHost; }
/**
* @brief Set URL port.
* @brief Sets URL port.
*
* @param port URL port.
*/
void SetPort(uint16_t port) { m_port = port; }
/**
* @brief Set URL path.
* @brief Sets URL path.
*
* @param path URL path.
*/
void SetPath(const std::string& encodedPath) { m_encodedPath = encodedPath; }
/**
* @brief Set the query parameters from an existing query parameter map.
* @brief Sets the query parameters from an existing query parameter map.
*
* @remark Keys and values in \p queryParameters are expected to be URL-encoded.
* @note Keys and values in \p queryParameters are expected to be URL-encoded.
*
* @param queryParameters
*/
@ -148,7 +149,7 @@ namespace Azure { namespace Core {
// ===== APIs for mutating URL state: ======
/**
* @brief Append an element of URL path.
* @brief Appends an element of URL path.
*
* @param path URL path element to append.
*/
@ -166,7 +167,7 @@ namespace Azure { namespace Core {
* will be encoded before adding to the URL. Use \p isValueEncoded = true when the
* value is already encoded.
*
* @remark This function overrides the value of existing query parameters.
* @note Overrides the value of existing query parameters.
*
* @param encodedKey Name of the query parameter, already encoded.
* @param encodedValue Value of the query parameter, already encoded.
@ -188,7 +189,7 @@ namespace Azure { namespace Core {
/************** API to read values from Url ***************/
/**
* @brief Get URL host.
* @brief Gets URL host.
*
*/
const std::string& GetHost() const { return m_host; }
@ -201,9 +202,9 @@ namespace Azure { namespace Core {
const std::string& GetPath() const { return m_encodedPath; }
/**
* @brief Get the port number set for the URL.
* @brief Gets the port number set for the URL.
*
* @remark If the port was not set for the URL, the returned port is 0. An HTTP request cannot
* @note If the port was not set for the URL, the returned port is 0. An HTTP request cannot
* be performed to port zero, an HTTP client is expected to set the default port depending on
* the request's schema when the port was not defined in the URL.
*
@ -212,9 +213,9 @@ namespace Azure { namespace Core {
uint16_t GetPort() const { return m_port; }
/**
* @brief Get a copy of the list of query parameters from the URL.
* @brief Gets a copy of the list of query parameters from the URL.
*
* @remark The query parameters are URL-encoded.
* @note The query parameters are URL-encoded.
*
* @return A copy of the query parameters map.
*/
@ -224,20 +225,20 @@ namespace Azure { namespace Core {
}
/**
* @brief Get the URL scheme.
* @brief Gets the URL scheme.
*
*/
const std::string& GetScheme() const { return m_scheme; };
/**
* @brief Get the path and query parameters.
* @brief Gets the path and query parameters.
*
* @return Relative URL with URL-encoded query parameters.
*/
std::string GetRelativeUrl() const;
/**
* @brief Get Scheme, host, path and query parameters.
* @brief Gets Scheme, host, path and query parameters.
*
* @return Absolute URL with URL-encoded query parameters.
*/

6
sdk/core/azure-core/inc/azure/core/uuid.hpp
View File

@ -42,8 +42,8 @@ namespace Azure { namespace Core {
public:
/**
* Gets UUID as a string.
* @details A string is in canonical format (4-2-2-2-6 lowercase hex and dashes only)
* @brief Gets Uuid as a string.
* @details A string is in canonical format (4-2-2-2-6 lowercase hex and dashes only).
*/
std::string ToString()
{
@ -76,7 +76,7 @@ namespace Azure { namespace Core {
}
/**
* @brief Create a new random UUID.
* @brief Creates a new random UUID.
*
*/
static Uuid CreateUuid()