Update all the doc comments and add WDocumention

zurex · zurex · commit 4f5255ae4d7a · 2025-04-23T14:55:39.000Z
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -603,6 +603,14 @@ if(OTELCPP_MAINTAINER_MODE)
     add_compile_options(-Werror)
     add_compile_options(-Wextra)
 
+    # Check if the compiler supports -Wdocumentation
+    include(CheckCXXCompilerFlag)
+    check_cxx_compiler_flag("-Wdocumentation" CLANG_SUPPORTS_DOCUMENTATION)
+    if(CLANG_SUPPORTS_DOCUMENTATION)
+      message(STATUS "Adding -Wdocumentation flag for Clang")
+      add_compile_options(-Wdocumentation)
+    endif()
+
     # Tested with Clang 11.0 on github.
     if(CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 11.0)
       message(STATUS "Building with additional warnings for clang.")
diff --git a/api/include/opentelemetry/common/attribute_value.h b/api/include/opentelemetry/common/attribute_value.h
@@ -23,7 +23,7 @@ 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
 /// \parblock The OpenTelemetry C++ API currently supports several attribute
 /// value types that are not covered by the OpenTelemetry specification:
 ///  - \c uint64_t
diff --git a/api/include/opentelemetry/common/key_value_iterable.h b/api/include/opentelemetry/common/key_value_iterable.h
@@ -44,12 +44,12 @@ class NoopKeyValueIterable : public KeyValueIterable
 
   /**
    * Iterate over key-value pairs
-   * @param callback a callback to invoke for each key-value. If the callback returns false,
+   * 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
    */
   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;
   }
diff --git a/api/include/opentelemetry/common/key_value_iterable_view.h b/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,7 +130,7 @@ inline static const common::KeyValueIterable &MakeAttributes(
 /**
  * Utility function to help to make a attribute view from a key-value iterable object
  *
- * @param attributes
+ * @param arg The key-value iterable object
  * @return nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>
  */
 template <
diff --git a/api/include/opentelemetry/context/runtime_context.h b/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 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;
diff --git a/api/include/opentelemetry/logs/event_logger.h b/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
diff --git a/api/include/opentelemetry/semconv/incubating/process_attributes.h b/api/include/opentelemetry/semconv/incubating/process_attributes.h
@@ -133,8 +133,7 @@ static constexpr const char *kProcessInteractive = "process.interactive";
  * <p>
  * Control groups (cgroups) are a kernel feature used to organize and manage process resources. This
  * attribute provides the path(s) to the cgroup(s) associated with the process, which should match
- * the contents of the <a
- * href="https://man7.org/linux/man-pages/man7/cgroups.7.html">/proc/[PID]/cgroup</a> file.
+ * the contents of the <a href="https://man7.org/linux/man-pages/man7/cgroups.7.html">/proc/[PID]/cgroup</a> file.
  */
 static constexpr const char *kProcessLinuxCgroup = "process.linux.cgroup";
 
diff --git a/api/include/opentelemetry/semconv/incubating/system_metrics.h b/api/include/opentelemetry/semconv/incubating/system_metrics.h
@@ -277,12 +277,13 @@ static inline nostd::shared_ptr<metrics::ObservableInstrument> CreateAsyncDouble
  * Time disk spent activated
  * <p>
  * The real elapsed time ("wall clock") used in the I/O path (time from operations running in
- * parallel are not counted). Measured as: <ul> <li>Linux: Field 13 from <a
- * href="https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats">procfs-diskstats</a></li>
- *   <li>Windows: The complement of
- * <a
- * href="https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained">"Disk%
- * Idle Time"</a> performance counter: @code uptime * (100 - "Disk\% Idle Time") / 100 @endcode</li>
+ * parallel are not counted). Measured as: <ul> 
+ *  <li>Linux: Field 13 from 
+ *    <a href="https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats">procfs-diskstats</a>
+ *  </li>
+ *  <li>Windows: The complement of 
+ *    <a href="https://learn.microsoft.com/archive/blogs/askcore/ windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained">"Disk% Idle Time"</a> 
+ * performance counter: @code uptime * (100 - "Disk\% Idle Time") / 100 @endcode</li>
  * </ul>
  * <p>
  * counter
@@ -395,8 +396,8 @@ CreateAsyncDoubleMetricSystemDiskMerged(metrics::Meter *meter)
  * Sum of the time each operation took to complete
  * <p>
  * Because it is the sum of time each request took, parallel-issued requests each contribute to make
- * the count grow. Measured as: <ul> <li>Linux: Fields 7 & 11 from <a
- * href="https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats">procfs-diskstats</a></li>
+ * the count grow. Measured as: <ul> <li>Linux: Fields 7 & 11 from 
+ * <a href="https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats">procfs-diskstats</a></li>
  *   <li>Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter
  * (similar for Writes)</li>
  * </ul>
@@ -608,9 +609,9 @@ CreateAsyncDoubleMetricSystemFilesystemUtilization(metrics::Meter *meter)
  * swapping <p> This is an alternative to @code system.memory.usage @endcode metric with @code
  * state=free @endcode. Linux starting from 3.14 exports "available" memory. It takes "free" memory
  * as a baseline, and then factors in kernel-specific values. This is supposed to be more accurate
- * than just "free" memory. For reference, see the calculations <a
- * href="https://superuser.com/a/980821">here</a>. See also @code MemAvailable @endcode in <a
- * href="https://man7.org/linux/man-pages/man5/proc.5.html">/proc/meminfo</a>. <p> updowncounter
+ * than just "free" memory. For reference, see the calculations 
+ * <a href="https://superuser.com/a/980821">here</a>. See also @code MemAvailable @endcode in 
+ * <a href="https://man7.org/linux/man-pages/man5/proc.5.html">/proc/meminfo</a>. <p> updowncounter
  */
 static constexpr const char *kMetricSystemLinuxMemoryAvailable = "system.linux.memory.available";
 static constexpr const char *descrMetricSystemLinuxMemoryAvailable =
@@ -655,10 +656,10 @@ CreateAsyncDoubleMetricSystemLinuxMemoryAvailable(metrics::Meter *meter)
  * <p>
  * The sum over the @code reclaimable @endcode and @code unreclaimable @endcode state values in
  * @code linux.memory.slab.usage @endcode SHOULD be equal to the total slab memory available on the
- * system. Note that the total slab memory is not constant and may vary over time. See also the <a
- * href="https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics">Slab
- * allocator</a> and @code Slab @endcode in <a
- * href="https://man7.org/linux/man-pages/man5/proc.5.html">/proc/meminfo</a>. <p> updowncounter
+ * system. Note that the total slab memory is not constant and may vary over time. See also the 
+ * <a href="https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics">Slab allocator</a> 
+ * and @code Slab @endcode in 
+ * <a href="https://man7.org/linux/man-pages/man5/proc.5.html">/proc/meminfo</a>. <p> updowncounter
  */
 static constexpr const char *kMetricSystemLinuxMemorySlabUsage = "system.linux.memory.slab.usage";
 static constexpr const char *descrMetricSystemLinuxMemorySlabUsage =
@@ -739,10 +740,10 @@ CreateAsyncDoubleMetricSystemMemoryLimit(metrics::Meter *meter)
 /**
  * Shared memory used (mostly by tmpfs).
  * <p>
- * Equivalent of @code shared @endcode from <a
- * href="https://man7.org/linux/man-pages/man1/free.1.html">@code free @endcode command</a> or
- * @code Shmem @endcode from <a href="https://man7.org/linux/man-pages/man5/proc.5.html">@code
- * /proc/meminfo @endcode</a>" <p> updowncounter
+ * Equivalent of @code shared @endcode from 
+ * <a href="https://man7.org/linux/man-pages/man1/free.1.html"> @code free @endcode command</a> or
+ * @code Shmem @endcode from 
+ * <a href="https://man7.org/linux/man-pages/man5/proc.5.html"> @code /proc/meminfo @endcode</a>" <p> updowncounter
  */
 static constexpr const char *kMetricSystemMemoryShared = "system.memory.shared";
 static constexpr const char *descrMetricSystemMemoryShared =
@@ -902,13 +903,11 @@ CreateAsyncDoubleMetricSystemNetworkConnections(metrics::Meter *meter)
  * <p>
  * Measured as:
  * <ul>
- *   <li>Linux: the @code drop @endcode column in @code /proc/dev/net @endcode (<a
- * href="https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html">source</a>)</li>
- *   <li>Windows: <a
- * href="https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2">@code
- * InDiscards @endcode/@code OutDiscards @endcode</a> from <a
- * href="https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2">@code
- * GetIfEntry2 @endcode</a></li>
+ *   <li>Linux: the @code drop @endcode column in @code /proc/dev/net @endcode (
+ *   <a href="https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html">source</a>)</li>
+ *   <li>Windows: 
+ * <a href="https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2"> @code InDiscards @endcode/@code OutDiscards @endcode</a> 
+ * from <a href="https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2"> @code GetIfEntry2 @endcode</a></li>
  * </ul>
  * <p>
  * counter
@@ -951,13 +950,11 @@ CreateAsyncDoubleMetricSystemNetworkDropped(metrics::Meter *meter)
  * <p>
  * Measured as:
  * <ul>
- *   <li>Linux: the @code errs @endcode column in @code /proc/dev/net @endcode (<a
- * href="https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html">source</a>).</li>
- *   <li>Windows: <a
- * href="https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2">@code
- * InErrors @endcode/@code OutErrors @endcode</a> from <a
- * href="https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2">@code
- * GetIfEntry2 @endcode</a>.</li>
+ *   <li>Linux: the @code errs @endcode column in @code /proc/dev/net @endcode (
+ * <a href="https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html">source</a>).</li>
+ *   <li>Windows: 
+ * <a href="https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2"> @code InErrors @endcode/@code OutErrors @endcode</a> 
+ * from <a href="https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2"> @code GetIfEntry2 @endcode</a>.</li>
  * </ul>
  * <p>
  * counter
diff --git a/api/include/opentelemetry/semconv/service_attributes.h b/api/include/opentelemetry/semconv/service_attributes.h
@@ -23,8 +23,8 @@ namespace service
  * Logical name of the service.
  * <p>
  * MUST be the same for all instances of horizontally scaled services. If the value was not
- * specified, SDKs MUST fallback to @code unknown_service: @endcode concatenated with <a
- * href="process.md">@code process.executable.name @endcode</a>, e.g. @code unknown_service:bash
+ * specified, SDKs MUST fallback to @code unknown_service: @endcode concatenated 
+ * with <a href="process.md">@code process.executable.name @endcode</a>, e.g. @code unknown_service:bash
  * @endcode. If @code process.executable.name @endcode is not available, the value MUST be set to
  * @code unknown_service @endcode.
  */
diff --git a/exporters/memory/include/opentelemetry/exporters/memory/in_memory_metric_exporter_factory.h b/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,
diff --git a/exporters/memory/include/opentelemetry/exporters/memory/in_memory_span_exporter.h b/exporters/memory/include/opentelemetry/exporters/memory/in_memory_span_exporter.h
@@ -81,7 +81,7 @@ class InMemorySpanExporter final : public opentelemetry::sdk::trace::SpanExporte
   }
 
   /**
-   * @param timeout an optional value containing the timeout of the exporter
+   * 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
    */
diff --git a/exporters/memory/src/in_memory_metric_exporter_factory.cc b/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)
diff --git a/sdk/include/opentelemetry/sdk/common/atomic_unique_ptr.h b/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())); }
 
diff --git a/sdk/include/opentelemetry/sdk/logs/multi_recordable.h b/sdk/include/opentelemetry/sdk/logs/multi_recordable.h
@@ -93,7 +93,7 @@ class MultiRecordable final : public Recordable
 
   /**
    * Set Resource of this log
-   * @param Resource the resource to set
+   * @param resource the resource to set
    */
   void SetResource(const opentelemetry::sdk::resource::Resource &resource) noexcept override;
 
diff --git a/sdk/include/opentelemetry/sdk/logs/read_write_log_record.h b/sdk/include/opentelemetry/sdk/logs/read_write_log_record.h
@@ -162,7 +162,7 @@ class ReadWriteLogRecord final : public ReadableLogRecord
 
   /**
    * Set Resource of this log
-   * @param Resource the resource to set
+   * @param resource the resource to set
    */
   void SetResource(const opentelemetry::sdk::resource::Resource &resource) noexcept override;
 
diff --git a/sdk/include/opentelemetry/sdk/logs/recordable.h b/sdk/include/opentelemetry/sdk/logs/recordable.h
@@ -32,7 +32,7 @@ class Recordable : public opentelemetry::logs::LogRecord
 public:
   /**
    * Set Resource of this log
-   * @param Resource the resource to set
+   * @param resource the resource to set
    */
   virtual void SetResource(const opentelemetry::sdk::resource::Resource &resource) noexcept = 0;
 
diff --git a/sdk/include/opentelemetry/sdk/metrics/meter_context.h b/sdk/include/opentelemetry/sdk/metrics/meter_context.h
@@ -150,7 +150,7 @@ class MeterContext : public std::enable_shared_from_this<MeterContext>
    * NOTE - INTERNAL method, can change in future.
    * Adds a meter to the list of configured meters in thread safe manner.
    *
-   * @param meter
+   * @param meter The meter to be added.
    */
   void AddMeter(const std::shared_ptr<Meter> &meter);
 
diff --git a/sdk/include/opentelemetry/sdk/trace/recordable.h b/sdk/include/opentelemetry/sdk/trace/recordable.h
@@ -59,7 +59,7 @@ class Recordable
    * @param name the name of the attribute
    * @param value the attribute value
    */
-  virtual void SetAttribute(nostd::string_view key,
+  virtual void SetAttribute(nostd::string_view name,
                             const opentelemetry::common::AttributeValue &value) noexcept = 0;
 
   /**
@@ -137,7 +137,6 @@ class Recordable
 
   /**
    * Set the trace flags of the span.
-   * @param flags the flags to set
    */
   virtual void SetTraceFlags(opentelemetry::trace::TraceFlags /* flags */) noexcept {}
 
@@ -149,7 +148,7 @@ class Recordable
 
   /**
    * Set Resource of the span
-   * @param Resource the resource to set
+   * @param resource the resource to set
    */
   virtual void SetResource(const opentelemetry::sdk::resource::Resource &resource) noexcept = 0;
 
diff --git a/sdk/include/opentelemetry/sdk/trace/sampler.h b/sdk/include/opentelemetry/sdk/trace/sampler.h
@@ -80,7 +80,7 @@ class Sampler
    * @param trace_id the TraceId for the new Span. This will be identical to that in
    *        the parentContext, unless this is a root span.
    * @param name the name of the new Span.
-   * @param spanKind the opentelemetry::trace::SpanKind of the Span.
+   * @param span_kind the opentelemetry::trace::SpanKind of the Span.
    * @param attributes list of AttributeValue with their keys.
    * @param links Collection of links that will be associated with the Span to be created.
    * @return sampling result whether span should be sampled or not.

Original file line number	Diff line number	Diff line change
`@@ -44,12 +44,12 @@ class NoopKeyValueIterable : public KeyValueIterable`
`44`	`44`
`45`	`45`	`/**`
`46`	`46`	`* Iterate over key-value pairs`
`47`		`- * @param callback a callback to invoke for each key-value. If the callback returns false,`
	`47`	`+ * A callback to invoke for each key-value. If the callback returns false,`
`48`	`48`	`* the iteration is aborted.`
`49`	`49`	`* @return true if every key-value pair was iterated over`
`50`	`50`	`*/`
`51`	`51`	`bool ForEachKeyValue(`
`52`		`- nostd::function_ref<bool(nostd::string_view, common::AttributeValue)>) const noexcept override`
	`52`	`+ nostd::function_ref<bool(nostd::string_view, common::AttributeValue)> /callback/) const noexcept override`
`53`	`53`	`{`
`54`	`54`	`return true;`
`55`	`55`	`}`
Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ class OPENTELEMETRY_DEPRECATED EventLogger`
`42`	`42`	`* Emit a event Log Record object with arguments`
`43`	`43`	`*`
`44`	`44`	`* @param event_name Event name`
`45`		`- * @tparam args Arguments which can be used to set data of log record by type.`
	`45`	`+ * @param args Arguments which can be used to set data of log record by type.`
`46`	`46`	`* Severity -> severity, severity_text`
`47`	`47`	`* string_view -> body`
`48`	`48`	`* AttributeValue -> body`