[DOC] Update doc comments to pass -WDocumention check (#3375)

Author: zurex

api/include/opentelemetry/common/attribute_value.h

@@ -23,7 +23,8 @@ namespace common
 ///    (IEEE 754-1985) or signed 64 bit integer.
 ///  - Homogenous arrays of primitive type values.
 ///
-/// \warning
+/// \warning The OpenTelemetry C++ API does not support the following attribute:
+///  uint64_t, nostd::span<const uint64_t>, and nostd::span<uint8_t> types.
 /// \parblock The OpenTelemetry C++ API currently supports several attribute
 /// value types that are not covered by the OpenTelemetry specification:
 ///  - \c uint64_t

api/include/opentelemetry/common/key_value_iterable.h

@@ -43,13 +43,12 @@ class NoopKeyValueIterable : public KeyValueIterable
   ~NoopKeyValueIterable() override = default;
 
   /**
-   * Iterate over key-value pairs
-   * @param callback a callback to invoke for each key-value. If the callback returns false,
-   * the iteration is aborted.
-   * @return true if every key-value pair was iterated over
+   * No-op implementation: does not invoke the callback, even if key-value pairs are present.
+   * @return true without iterating or invoking the callback
    */
   bool ForEachKeyValue(
-      nostd::function_ref<bool(nostd::string_view, common::AttributeValue)>) const noexcept override
+      nostd::function_ref<bool(nostd::string_view, common::AttributeValue)> /*callback*/)
+      const noexcept override
   {
     return true;
   }

api/include/opentelemetry/common/key_value_iterable_view.h

@@ -91,7 +91,7 @@ KeyValueIterableView<T> MakeKeyValueIterableView(const T &container) noexcept
 /**
  * Utility function to help to make a attribute view from initializer_list
  *
- * @param attributes
+ * @param attributes The initializer_list of key-value pairs
  * @return nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>
  */
 inline static nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>
@@ -105,7 +105,7 @@ MakeAttributes(std::initializer_list<std::pair<nostd::string_view, common::Attri
 /**
  * Utility function to help to make a attribute view from a span
  *
- * @param attributes
+ * @param attributes The span of key-value pairs
  * @return nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>
  */
 inline static nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>
@@ -118,7 +118,7 @@ MakeAttributes(
 /**
  * Utility function to help to make a attribute view from a KeyValueIterable
  *
- * @param attributes
+ * @param attributes The KeyValueIterable of key-value pairs
  * @return common::KeyValueIterable
  */
 inline static const common::KeyValueIterable &MakeAttributes(
@@ -130,16 +130,17 @@ inline static const common::KeyValueIterable &MakeAttributes(
 /**
  * Utility function to help to make a attribute view from a key-value iterable object
  *
- * @param attributes
+ * @tparam ArgumentType  Expected to be ArgumentType
+ * @param attributes     The key-value iterable object
  * @return nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>
  */
 template <
     class ArgumentType,
     nostd::enable_if_t<common::detail::is_key_value_iterable<ArgumentType>::value> * = nullptr>
 inline static common::KeyValueIterableView<ArgumentType> MakeAttributes(
-    const ArgumentType &arg) noexcept
+    const ArgumentType &attributes) noexcept
 {
-  return common::KeyValueIterableView<ArgumentType>(arg);
+  return common::KeyValueIterableView<ArgumentType>(attributes);
 }
 
 }  // namespace common

api/include/opentelemetry/context/runtime_context.h

@@ -56,7 +56,7 @@ class OPENTELEMETRY_EXPORT RuntimeContextStorage
 
   /**
    * Set the current context.
-   * @param the new current context
+   * @param context The new current context
    * @return a token for the new current context. This never returns a nullptr.
    */
   virtual nostd::unique_ptr<Token> Attach(const Context &context) noexcept = 0;

api/include/opentelemetry/logs/event_logger.h

@@ -42,7 +42,7 @@ class OPENTELEMETRY_DEPRECATED EventLogger
    * Emit a event Log Record object with arguments
    *
    * @param event_name Event name
-   * @tparam args Arguments which can be used to set data of log record by type.
+   * @param args Arguments which can be used to set data of log record by type.
    *  Severity                                -> severity, severity_text
    *  string_view                             -> body
    *  AttributeValue                          -> body

exporters/memory/include/opentelemetry/exporters/memory/in_memory_metric_exporter_factory.h

@@ -24,7 +24,6 @@ class InMemoryMetricExporterFactory
   /// temporality selector.
   /// @param [out] data the InMemoryMetricData the exporter will write to,
   ///                   for the caller to inspect
-  /// @param [in] buffer_size number of entries to save in the circular buffer
   /// @param [in] temporality output temporality as a function of instrument kind
   static std::unique_ptr<opentelemetry::sdk::metrics::PushMetricExporter> Create(
       const std::shared_ptr<InMemoryMetricData> &data,

exporters/memory/include/opentelemetry/exporters/memory/in_memory_span_exporter.h

@@ -81,11 +81,12 @@ class InMemorySpanExporter final : public opentelemetry::sdk::trace::SpanExporte
   }
 
   /**
-   * @param timeout an optional value containing the timeout of the exporter
+   * Attempt to shut down the in-memory span exporter.
+   * @param timeout Timeout is an optional value containing the timeout of the exporter
    * note: passing custom timeout values is not currently supported for this exporter
    * @return Returns the status of the operation
    */
-  bool Shutdown(std::chrono::microseconds /* timeout */) noexcept override
+  bool Shutdown(std::chrono::microseconds timeout OPENTELEMETRY_MAYBE_UNUSED) noexcept override
   {
     is_shutdown_ = true;
     return true;

exporters/memory/src/in_memory_metric_exporter_factory.cc

@@ -35,7 +35,7 @@ namespace
 class InMemoryMetricExporter final : public sdk::metrics::PushMetricExporter
 {
 public:
-  /// @param buffer_size a required value that sets the size of the CircularBuffer
+  /// @param data The in-memory data to export to.
   /// @param temporality Output temporality as a function of instrument kind.
   InMemoryMetricExporter(const std::shared_ptr<InMemoryMetricData> &data,
                          const sdk::metrics::AggregationTemporalitySelector &temporality)

ext/include/opentelemetry/ext/http/client/curl/http_operation_curl.h

@@ -81,22 +81,24 @@ class HttpOperation
   /**
    * Old-school memory allocator
    *
-   * @param contents
-   * @param size
-   * @param nmemb
-   * @param userp
-   * @return
+   * @param contents Pointer to the data received from the server.
+   * @param size Size of each data element.
+   * @param nmemb Number of data elements.
+   * @param userp Pointer to the user-defined data structure for storing the received data.
+   * @return The number of bytes actually taken care of. If this differs from size * nmemb, it
+   * signals an error to libcurl.
    */
   static size_t WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp);
 
   /**
    * C++ STL std::vector allocator
    *
-   * @param ptr
-   * @param size
-   * @param nmemb
-   * @param data
-   * @return
+   * @param ptr Pointer to the data received from the server.
+   * @param size Size of each data element.
+   * @param nmemb Number of data elements.
+   * @param userp Pointer to the user-defined data structure for storing the received data.
+   * @return The number of bytes actually taken care of. If this differs from size * nmemb, it
+   * signals an error to libcurl.
    */
   static size_t WriteVectorHeaderCallback(void *ptr, size_t size, size_t nmemb, void *userp);
   static size_t WriteVectorBodyCallback(void *ptr, size_t size, size_t nmemb, void *userp);
@@ -138,11 +140,9 @@ class HttpOperation
    * Create local CURL instance for url and body
    * @param method   HTTP Method
    * @param url   HTTP URL
-   * @param callback
-   * @param request_mode   Sync or async
-   * @param request   Request Headers
-   * @param body   Request Body
-   * @param raw_response   Whether to parse the response
+   * @param request_headers   Request Headers
+   * @param request_body   Request Body
+   * @param is_raw_response   Whether to parse the response
    * @param http_conn_timeout   HTTP connection timeout in seconds
    * @param reuse_connection   Whether connection should be reused or closed
    * @param is_log_enabled   To intercept some information from cURL request
@@ -232,22 +232,16 @@ class HttpOperation
 
   /**
    * Return a copy of response headers
-   *
-   * @return
    */
   Headers GetResponseHeaders();
 
   /**
    * Return a copy of response body
-   *
-   * @return
    */
   inline const std::vector<uint8_t> &GetResponseBody() const noexcept { return response_body_; }
 
   /**
    * Return a raw copy of response headers+body
-   *
-   * @return
    */
   inline const std::vector<uint8_t> &GetRawResponse() const noexcept { return raw_response_; }
 
@@ -265,7 +259,7 @@ class HttpOperation
    * Perform curl message, this function only can be called in the polling thread and it can only
    * be called when got a CURLMSG_DONE.
    *
-   * @param code
+   * @param code CURLcode
    */
   void PerformCurlMessage(CURLcode code);
 

sdk/include/opentelemetry/sdk/common/atomic_unique_ptr.h

@@ -61,7 +61,7 @@ class AtomicUniquePtr
 
   /**
    * Atomically swap the pointer with another.
-   * @param ptr the pointer to swap with
+   * @param other The pointer to swap with
    */
   void Swap(std::unique_ptr<T> &other) noexcept { other.reset(ptr_.exchange(other.release())); }