[DOC] Update doc comments to pass -WDocumention check

.clang-format

@@ -70,4 +70,6 @@ AttributeMacros:
   - OPENTELEMETRY_EXPORT
   - OPENTELEMETRY_SANITIZER_NO_MEMORY
   - OPENTELEMETRY_SANITIZER_NO_THREAD
-  - OPENTELEMETRY_SANITIZER_NO_ADDRESS
+  - OPENTELEMETRY_SANITIZER_NO_ADDRESS
+
+CommentPragmas: <a.*>|</a>

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.")

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

api/include/opentelemetry/semconv/incubating/process_attributes.h

@@ -147,8 +147,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";
 

api/include/opentelemetry/semconv/incubating/system_metrics.h

@@ -275,12 +275,14 @@ 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
@@ -393,8 +395,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>
@@ -606,9 +608,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 =
@@ -653,10 +655,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 =
@@ -737,10 +739,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 =
@@ -900,13 +902,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
@@ -949,13 +949,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

api/include/opentelemetry/semconv/incubating/url_attributes.h

@@ -23,8 +23,8 @@ namespace url
  * Domain extracted from the @code url.full @endcode, such as "opentelemetry.io".
  * <p>
  * In some cases a URL may refer to an IP and/or port directly, without a domain name. In this case,
- * the IP address would go to the domain field. If the URL contains a <a
- * href="https://www.rfc-editor.org/rfc/rfc2732#section-2">literal IPv6 address</a> enclosed by
+ * the IP address would go to the domain field. If the URL contains a
+ * <a href="https://www.rfc-editor.org/rfc/rfc2732#section-2">literal IPv6 address</a> enclosed by
  * @code [ @endcode and @code ] @endcode, the @code [ @endcode and @code ] @endcode characters
  * should also be captured in the domain field.
  */
@@ -45,8 +45,8 @@ static constexpr const char *kUrlExtension = "url.extension";
 static constexpr const char *kUrlFragment = "url.fragment";
 
 /**
- * Absolute URL describing a network resource according to <a
- * href="https://www.rfc-editor.org/rfc/rfc3986">RFC3986</a> <p> For network calls, URL usually has
+ * Absolute URL describing a network resource according to
+ * <a href="https://www.rfc-editor.org/rfc/rfc3986">RFC3986</a> <p> For network calls, URL usually has
  * @code scheme://host[:port][path][?query][#fragment] @endcode format, where the fragment is not
  * transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. <p>
  * @code url.full @endcode MUST NOT contain credentials passed via URL in form of @code
@@ -60,15 +60,12 @@ static constexpr const char *kUrlFragment = "url.fragment";
  * Query string values for the following keys SHOULD be redacted by default and replaced by the
  * value @code REDACTED @endcode:
  * <ul>
- *   <li><a
- * href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth">@code
- * AWSAccessKeyId @endcode</a></li> <li><a
- * href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth">@code
- * Signature @endcode</a></li> <li><a
- * href="https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token">@code sig
- * @endcode</a></li> <li><a
- * href="https://cloud.google.com/storage/docs/access-control/signed-urls">@code X-Goog-Signature
- * @endcode</a></li>
+ *   <li>
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth"> @code AWSAccessKeyId @endcode</a>
+ * </li> <li>
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth"> @code Signature @endcode</a>
+ * </li> <li><a href="https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token"> @code sig @endcode</a>
+ * </li> <li><a href="https://cloud.google.com/storage/docs/access-control/signed-urls">@code X-Goog-Signature @endcode</a></li>
  * </ul>
  * <p>
  * This list is subject to change over time.
@@ -110,15 +107,11 @@ static constexpr const char *kUrlPort = "url.port";
  * can identify it. <p>
  *
  * Query string values for the following keys SHOULD be redacted by default and replaced by the
- * value @code REDACTED @endcode: <ul> <li><a
- * href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth">@code
- * AWSAccessKeyId @endcode</a></li> <li><a
- * href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth">@code
- * Signature @endcode</a></li> <li><a
- * href="https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token">@code sig
- * @endcode</a></li> <li><a
- * href="https://cloud.google.com/storage/docs/access-control/signed-urls">@code X-Goog-Signature
- * @endcode</a></li>
+ * value @code REDACTED @endcode: <ul> <li>
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth"> @code AWSAccessKeyId @endcode</a></li>
+ * <li><a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth"> @code Signature @endcode</a></li>
+ * <li><a href="https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token"> @code sig @endcode</a></li>
+ * <li><a href="https://cloud.google.com/storage/docs/access-control/signed-urls">@code X-Goog-Signature @endcode</a></li>
  * </ul>
  * <p>
  * This list is subject to change over time.
@@ -131,8 +124,9 @@ static constexpr const char *kUrlQuery = "url.query";
 /**
  * The highest registered url domain, stripped of the subdomain.
  * <p>
- * This value can be determined precisely with the <a href="https://publicsuffix.org/">public suffix
- * list</a>. For example, the registered domain for @code foo.example.com @endcode is @code
+ * This value can be determined precisely with the
+ * <a href="https://publicsuffix.org/">public suffix list</a>.
+ * For example, the registered domain for @code foo.example.com @endcode is @code
  * example.com @endcode. Trying to approximate this by simply taking the last two labels will not
  * work well for TLDs such as @code co.uk @endcode.
  */
@@ -155,16 +149,16 @@ static constexpr const char *kUrlScheme = "url.scheme";
 static constexpr const char *kUrlSubdomain = "url.subdomain";
 
 /**
- * The low-cardinality template of an <a
- * href="https://www.rfc-editor.org/rfc/rfc3986#section-4.2">absolute path reference</a>.
+ * The low-cardinality template of an
+ * <a href="https://www.rfc-editor.org/rfc/rfc3986#section-4.2">absolute path reference</a>.
  */
 static constexpr const char *kUrlTemplate = "url.template";
 
 /**
  * The effective top level domain (eTLD), also known as the domain suffix, is the last part of the
  * domain name. For example, the top level domain for example.com is @code com @endcode. <p> This
- * value can be determined precisely with the <a href="https://publicsuffix.org/">public suffix
- * list</a>.
+ * value can be determined precisely with the
+ * <a href="https://publicsuffix.org/">public suffix list</a>.
  */
 static constexpr const char *kUrlTopLevelDomain = "url.top_level_domain";
 

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.
  */