Doc changes for HTTP and removing the "More" link (#2332)

* update docs from classes

* remove more link from classes part II

* http docs

* Update sdk/core/azure-core/inc/azure/core/http/http.hpp

Co-authored-by: Rick Winter <rick.winter@microsoft.com>

* Update cmake-modules/AzureDoxygen.cmake

* doc updates

* update RFC

Co-authored-by: Rick Winter <rick.winter@microsoft.com>

cmake-modules/AzureDoxygen.cmake

@@ -38,6 +38,8 @@ function(generate_documentation PROJECT_NAME PROJECT_VERSION)
         # Use MathJax instead of latex to render formulas
         set(DOXYGEN_USE_MATHJAX YES)
 
+        set(DOXYGEN_REPEAT_BRIEF NO)
+
         doxygen_add_docs(${PROJECT_NAME}-docs
             ALL
             COMMENT "Generate documentation for ${PROJECT_NAME}")

sdk/core/azure-core/inc/azure/core/context.hpp

@@ -23,7 +23,6 @@ namespace Azure { namespace Core {
 
   /**
    * @brief An exception thrown when an operation is cancelled.
-   *
    */
   class OperationCancelledException final : public std::runtime_error {
   public:
@@ -39,13 +38,11 @@ namespace Azure { namespace Core {
 
   /**
    * @brief A context is a node within a tree that represents deadlines and key/value pairs.
-   *
    */
   class Context final {
   public:
     /**
      * @brief A key used to store and retrieve data in an #Azure::Core::Context object.
-     *
      */
     class Key final {
       Key const* m_uniqueAddress;

sdk/core/azure-core/inc/azure/core/credentials/credentials.hpp

@@ -22,7 +22,6 @@ namespace Azure { namespace Core { namespace Credentials {
 
   /**
    * @brief An access token is used to authenticate requests.
-   *
    */
   struct AccessToken final
   {
@@ -41,7 +40,6 @@ namespace Azure { namespace Core { namespace Credentials {
 
   /**
    * @brief Context for getting token.
-   *
    */
   struct TokenRequestContext final
   {
@@ -54,7 +52,6 @@ namespace Azure { namespace Core { namespace Credentials {
 
   /**
    * @brief A base type of credential that uses Azure::Core::AccessToken to authenticate requests.
-   *
    */
   class TokenCredential {
   public:
@@ -84,7 +81,6 @@ namespace Azure { namespace Core { namespace Credentials {
 
   /**
    * @brief An exception that gets thrown when an authentication error occurs.
-   *
    */
   class AuthenticationException final : public std::exception {
     std::string m_message;

sdk/core/azure-core/inc/azure/core/diagnostics/logger.hpp

@@ -14,7 +14,6 @@
 namespace Azure { namespace Core { namespace Diagnostics {
   /**
    * @brief Log message handler.
-   *
    */
   class Logger final {
   public:

sdk/core/azure-core/inc/azure/core/dll_import_export.hpp

@@ -97,46 +97,39 @@
 
 /**
  * @brief Azure SDK abstractions.
- *
  */
 namespace Azure {
 
 /**
  * @brief Abstractions commonly used by Azure SDK client libraries.
- *
  */
 namespace Core {
 
   /**
    * @brief Credential-related abstractions.
-   *
    */
   namespace Credentials {
   }
 
   /**
    * @brief Cryptography-related abstractions.
-   *
    */
   namespace Cryptography {
   }
 
   /**
    * @brief Diagnostics-related abstractions, such as logging.
-   *
    */
   namespace Diagnostics {
   }
 
   /**
    * @brief Abstractions related to HTTP transport layer.
-   *
    */
   namespace Http {
 
     /**
      * @brief Abstractions related to controlling the behavior of HTTP requests.
-     *
      */
     namespace Policies {
     }
@@ -144,7 +137,6 @@ namespace Core {
 
   /**
    * @brief Abstractions related to communications with Azure.
-   *
    */
   namespace IO {
   }

sdk/core/azure-core/inc/azure/core/etag.hpp

@@ -17,7 +17,6 @@ namespace Azure {
 
 /**
  * @brief Represents an HTTP validator.
- *
  */
 class ETag final {
   // ETag is a validator based on https://tools.ietf.org/html/rfc7232#section-2.3.2
@@ -135,7 +134,7 @@ public:
    */
   bool HasValue() const { return m_value.HasValue(); }
 
-  /*
+  /**
    * @brief Returns the resource metadata represented as a string.
    * @return #std::string
    */

sdk/core/azure-core/inc/azure/core/exception.hpp

@@ -19,7 +19,6 @@
 namespace Azure { namespace Core {
   /**
    * @brief An error while trying to send a request to Azure service.
-   *
    */
   class RequestFailedException : public std::runtime_error {
   public:

sdk/core/azure-core/inc/azure/core/http/curl_transport.hpp

@@ -36,7 +36,6 @@ namespace Azure { namespace Core { namespace Http {
 
   /**
    * @brief Set the libcurl connection options like a proxy and CA path.
-   *
    */
   struct CurlTransportOptions final
   {
@@ -93,7 +92,6 @@ namespace Azure { namespace Core { namespace Http {
 
   /**
    * @brief Concrete implementation of an HTTP Transport that uses libcurl.
-   *
    */
   class CurlTransport final : public HttpTransport {
   private:

sdk/core/azure-core/inc/azure/core/http/http.hpp

@@ -51,8 +51,8 @@ namespace Azure { namespace Core { namespace Http {
 
   /*********************  Exceptions  **********************/
   /**
-   * @brief HTTP transport layer error.
-   *
+   * @brief Consistent interface to handle errors occurred while performing an HTTP
+   * Request.
    */
   class TransportException final : public Azure::Core::RequestFailedException {
   public:
@@ -71,9 +71,9 @@ namespace Azure { namespace Core { namespace Http {
   };
 
   /**
-   * @brief Defines a range of bytes within an HTTP resource, starting at an `Offset` and ending at
-   * `Offset + Length - 1` inclusively.
+   * @brief The range of bytes within an HTTP resource.
    *
+   * @note Starts at an `Offset` and ends at `Offset + Length - 1` inclusively.
    */
   struct HttpRange final
   {
@@ -91,22 +91,76 @@ namespace Azure { namespace Core { namespace Http {
   };
 
   /**
-   * HTTP request method.
-   *
+   * @brief The method to be performed on the resource identified by the Request.
    */
   class HttpMethod final {
   public:
     HttpMethod() = delete;
+
+    /**
+     * @brief Constructs a new HttpMethod from a given string.
+     *
+     * @note Won't check if \p value is a known HttpMethod defined as per any RFC.
+     *
+     * @param value A given string to represent the HttpMethod.
+     */
     explicit HttpMethod(std::string value) : m_value(std::move(value)) {}
+
+    /**
+     * @brief Compares two instances of `HttpMethod` for equality.
+     *
+     * @param other Some `HttpMethod` instance to compare with.
+     * @return `true` if instances are equal; otherwise, `false`.
+     */
     bool operator==(const HttpMethod& other) const { return m_value == other.m_value; }
+
+    /**
+     * @brief Compares two instances of `HttpMethod` for equality.
+     *
+     * @param other Some `HttpMethod` instance to compare with.
+     * @return `false` if instances are equal; otherwise, `true`.
+     */
     bool operator!=(const HttpMethod& other) const { return !(*this == other); }
+
+    /**
+     * @brief Returns the HttpMethod represented as a string.
+     */
     const std::string& ToString() const { return m_value; }
 
+    /**
+     * @brief The representation of a `GET` HttpMethod based on [RFC 7231]
+     * (https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1).
+     */
     AZ_CORE_DLLEXPORT const static HttpMethod Get;
+
+    /**
+     * @brief The representation of a `HEAD` HttpMethod based on [RFC 7231]
+     * (https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.2).
+     */
     AZ_CORE_DLLEXPORT const static HttpMethod Head;
+
+    /**
+     * @brief The representation of a `POST` HttpMethod based on [RFC 7231]
+     * (https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.3).
+     */
     AZ_CORE_DLLEXPORT const static HttpMethod Post;
+
+    /**
+     * @brief The representation of a `PUT` HttpMethod based on [RFC 7231]
+     * (https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.4).
+     */
     AZ_CORE_DLLEXPORT const static HttpMethod Put;
+
+    /**
+     * @brief The representation of a `DELETE` HttpMethod based on [RFC 7231]
+     * (https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.5).
+     */
     AZ_CORE_DLLEXPORT const static HttpMethod Delete;
+
+    /**
+     * @brief The representation of a `PATCH` HttpMethod based on [RFC 5789]
+     * (https://datatracker.ietf.org/doc/html/rfc5789).
+     */
     AZ_CORE_DLLEXPORT const static HttpMethod Patch;
 
   private:
@@ -118,8 +172,10 @@ namespace Azure { namespace Core { namespace Http {
   }} // namespace Policies::_internal
 
   /**
-   * @brief HTTP request.
+   * @brief A request message from a client to a server.
    *
+   * @details Includes, within the first line of the message, the HttpMethod to be applied to the
+   * resource, the URL of the resource, and the protocol version in use.
    */
   class Request final {
     friend class Azure::Core::Http::Policies::_internal::RetryPolicy;
@@ -160,7 +216,7 @@ namespace Azure { namespace Core { namespace Http {
     /**
      * @brief Construct an #Azure::Core::Http::Request.
      *
-     * @param httpMethod HTTP method.
+     * @param httpMethod HttpMethod.
      * @param url URL.
      * @param bodyStream #Azure::Core::IO::BodyStream.
      * @param shouldBufferResponse A boolean value indicating whether the returned response should
@@ -180,7 +236,7 @@ namespace Azure { namespace Core { namespace Http {
     /**
      * @brief Construct an #Azure::Core::Http::Request.
      *
-     * @param httpMethod HTTP method.
+     * @param httpMethod HttpMethod.
      * @param url URL.
      * @param bodyStream #Azure::Core::IO::BodyStream.
      */
@@ -193,7 +249,7 @@ namespace Azure { namespace Core { namespace Http {
     /**
      * @brief Construct an #Azure::Core::Http::Request.
      *
-     * @param httpMethod HTTP method.
+     * @param httpMethod HttpMethod.
      * @param url URL.
      * @param shouldBufferResponse A boolean value indicating whether the returned response should
      * be buffered or returned as a body stream instead.
@@ -203,7 +259,7 @@ namespace Azure { namespace Core { namespace Http {
     /**
      * @brief Construct an #Azure::Core::Http::Request.
      *
-     * @param httpMethod HTTP method.
+     * @param httpMethod HttpMethod.
      * @param url URL.
      */
     explicit Request(HttpMethod httpMethod, Url url);
@@ -230,7 +286,7 @@ namespace Azure { namespace Core { namespace Http {
 
     // Methods used by transport layer (and logger) to send request
     /**
-     * @brief Get HTTP method.
+     * @brief Get HttpMethod.
      *
      */
     HttpMethod GetMethod() const;

sdk/core/azure-core/inc/azure/core/http/http_status_code.hpp

@@ -13,7 +13,6 @@
 namespace Azure { namespace Core { namespace Http {
   /**
    * @brief Defines the possible HTTP status codes.
-   *
    */
   enum class HttpStatusCode
   {

sdk/core/azure-core/inc/azure/core/http/policies/policy.hpp

@@ -45,7 +45,6 @@ namespace Azure { namespace Core { namespace Http { namespace Policies {
   /**
    * @brief Telemetry options, used to configure telemetry parameters.
    * @note See https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy.
-   *
    */
   struct TelemetryOptions final
   {
@@ -121,7 +120,6 @@ namespace Azure { namespace Core { namespace Http { namespace Policies {
 
   /**
    * @brief HTTP transport options parameterize the HTTP transport adapter being used.
-   *
    */
   struct TransportOptions final
   {
@@ -260,7 +258,6 @@ namespace Azure { namespace Core { namespace Http { namespace Policies {
 
     /**
      * @brief HTTP retry policy.
-     *
      */
     class RetryPolicy
 #if !defined(TESTING_BUILD)

sdk/core/azure-core/inc/azure/core/http/raw_response.hpp

@@ -18,8 +18,8 @@
 
 namespace Azure { namespace Core { namespace Http {
   /**
-   * @brief Raw HTTP response.
-   *
+   * @brief After receiving and interpreting a request message, a server responds with an HTTP
+   * response message.
    */
   class RawResponse final {
 

sdk/core/azure-core/inc/azure/core/http/transport.hpp

@@ -15,7 +15,6 @@ namespace Azure { namespace Core { namespace Http {
 
   /**
    * @brief Base class for all HTTP transport implementations.
-   *
    */
   class HttpTransport {
   public:

sdk/core/azure-core/inc/azure/core/http/win_http_transport.hpp

@@ -125,7 +125,6 @@ namespace Azure { namespace Core { namespace Http {
   /**
    * @brief Sets the WinHTTP session and connection options used to customize the behavior of the
    * transport.
-   *
    */
   struct WinHttpTransportOptions final
   {
@@ -135,7 +134,6 @@ namespace Azure { namespace Core { namespace Http {
   /**
    * @brief Concrete implementation of an HTTP transport that uses WinHTTP when sending and
    * receiving requests and responses over the wire.
-   *
    */
   class WinHttpTransport final : public HttpTransport {
   private:

sdk/core/azure-core/inc/azure/core/internal/client_options.hpp

@@ -20,7 +20,6 @@ namespace Azure { namespace Core { namespace _internal {
   /**
    * @brief  Base type for all client option types, exposes various common client options like Retry
    * and Transport.
-   *
    */
   struct ClientOptions
   {

sdk/core/azure-core/inc/azure/core/internal/json/json_serializable.hpp

@@ -15,7 +15,6 @@ namespace Azure { namespace Core { namespace Json { namespace _internal {
 
   /**
    * @brief Interface for json-serializable components.
-   *
    */
   class JsonSerializable {
   public:

sdk/core/azure-core/inc/azure/core/internal/strings.hpp

@@ -16,7 +16,6 @@ namespace Azure { namespace Core { namespace _internal {
   /**
    * @brief Extend the functionality of std::string by offering static methods for string
    * operations.
-   *
    */
   struct StringExtensions final
   {

sdk/core/azure-core/inc/azure/core/io/body_stream.hpp

@@ -27,7 +27,6 @@ namespace Azure { namespace Core { namespace IO {
 
   /**
    * @brief Used to read data to/from a service.
-   *
    */
   class BodyStream {
   private:
@@ -117,7 +116,6 @@ namespace Azure { namespace Core { namespace IO {
 
   /**
    * @brief #Azure::Core::IO::BodyStream providing data from an initialized memory buffer.
-   *
    */
   class MemoryBodyStream final : public BodyStream {
   private:

sdk/core/azure-core/inc/azure/core/operation_status.hpp

@@ -20,7 +20,6 @@ namespace Azure { namespace Core {
 
   /**
    * @brief Long-running operation states.
-   *
    */
   class OperationStatus final {
     std::string m_value;

sdk/core/azure-core/inc/azure/core/url.hpp

@@ -40,8 +40,9 @@ namespace Azure { namespace Core {
 
   /**
    * @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.
+   *
+   * @details It can be parsed and initialized from a string that contains all URL components
+   * (scheme, host, path, etc.). Authority is not currently supported.
    */
   class Url final {
   private:

sdk/core/azure-core/inc/azure/core/uuid.hpp

@@ -23,7 +23,6 @@
 namespace Azure { namespace Core {
   /**
    * @brief Universally unique identifier.
-   *
    */
   class Uuid final {
 

sdk/core/azure-core/test/fault-injector/fault_injector_test.cpp

@@ -37,7 +37,6 @@ struct FaultInjectionClientOptions
 
 /**
  * @brief An special http policy to redirect requests to the Fault injector server.
- *
  */
 class FaultInjectionClient : public Azure::Core::Http::HttpTransport {
 private:

sdk/core/azure-core/test/perf/inc/azure/core/test/nullable_test.hpp

@@ -17,7 +17,6 @@ namespace Azure { namespace Core { namespace Test {
 
   /**
    * @brief Measure the Nullable object performance.
-   *
    */
   class NullableTest : public Azure::Perf::PerfTest {
   public: