[CI] Add Doxygen validation workflow (open-telemetry#3882)

Author: srgbtl

.github/workflows/doxygen-tidy.yaml

@@ -0,0 +1,40 @@
+name: doxygen-tidy
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  doxygen-lint:
+    name: Doxygen lint
+    runs-on: ubuntu-latest
+    env:
+      DOXYFILE_FOLDER: 'docs/public'
+      DOXYFILE_NAME: 'Doxyfile.lint'
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install doxygen
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen
+          echo "Installed Doxygen version: $(doxygen --version)"
+      - name: Analyze Doxygen comments
+        working-directory: ${{ env.DOXYFILE_FOLDER }}
+        run: |
+          mkdir /tmp/doxyoutput
+          doxygen ${{ env.DOXYFILE_NAME }}
+      - name: Check for Doxygen warnings
+        working-directory: ${{ env.DOXYFILE_FOLDER }}
+        run: |
+          if [ -s doxygen_warnings.log ]; then
+            echo "Doxygen warnings found:"
+            cat doxygen_warnings.log
+            exit 1
+          else
+            echo "No Doxygen warnings found."
+          fi

api/include/opentelemetry/logs/logger.h

@@ -292,10 +292,10 @@ class Logger
   /**
    * Log an event
    *
-   * @severity severity of the log
-   * @event_id event identifier of the log
-   * @format an utf-8 string following https://messagetemplates.org/
-   * @attributes key value pairs of the log
+   * @param severity severity of the log
+   * @param event_id event identifier of the log
+   * @param format an utf-8 string following https://messagetemplates.org/
+   * @param attributes key value pairs of the log
    */
   virtual void Log(Severity severity,
                    const EventId &event_id,

docs/public/Doxyfile

@@ -966,7 +966,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ./Overview.md
+USE_MDFILE_AS_MAINPAGE =
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

docs/public/Doxyfile.lint

@@ -0,0 +1,12 @@
+@INCLUDE = Doxyfile
+
+OUTPUT_DIRECTORY       = /tmp
+
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = NO
+WARN_LOGFILE           = doxygen_warnings.log
+QUIET                  = YES

sdk/include/opentelemetry/sdk/logs/batch_log_record_processor.h

@@ -156,6 +156,7 @@ class BatchLogRecordProcessor : public LogRecordProcessor
    * any time
    *
    * @param notify_force_flush Sequence to indicate whether to notify force flush completion.
+   * @param exporter The log exporter instance that handles exporting logs to the backend.
    * @param synchronization_data Synchronization data to be notified.
    */
   static void NotifyCompletion(uint64_t notify_force_flush,

sdk/include/opentelemetry/sdk/logs/logger.h

@@ -29,6 +29,7 @@ class Logger final : public opentelemetry::logs::Logger
    * Initialize a new logger.
    * @param name The name of this logger instance
    * @param context The logger provider that owns this logger.
+   * @param instrumentation_scope The instrumentation scope for this logger.
    */
   explicit Logger(
       opentelemetry::nostd::string_view name,

sdk/include/opentelemetry/sdk/logs/logger_provider.h

@@ -36,6 +36,8 @@ class OPENTELEMETRY_EXPORT LoggerProvider final : public opentelemetry::logs::Lo
    * @param processor The log record processor for this logger provider. This must
    * not be a nullptr.
    * @param resource  The resources for this logger provider.
+   * @param logger_configurator The scope configurator used to determine the configs for loggers
+   * created using this logger provider.
    */
   explicit LoggerProvider(
       std::unique_ptr<LogRecordProcessor> &&processor,
@@ -87,6 +89,7 @@ class OPENTELEMETRY_EXPORT LoggerProvider final : public opentelemetry::logs::Lo
    * @param library_name The version of the library.
    * @param library_version The version of the library.
    * @param schema_url The schema URL.
+   * @param attributes The attributes to be associated with the logger.
    */
   nostd::shared_ptr<opentelemetry::logs::Logger> GetLogger(
       nostd::string_view logger_name,

sdk/include/opentelemetry/sdk/metrics/meter_context.h

@@ -58,6 +58,8 @@ class MeterContext : public std::enable_shared_from_this<MeterContext>
    * Initialize a new meter provider
    * @param views The views to be configured with meter context.
    * @param resource  The resource for this meter context.
+   * @param meter_configurator A scope configurator defining the behavior of a meter associated with
+   * this meter context.
    */
   MeterContext(
       std::unique_ptr<ViewRegistry> views = std::unique_ptr<ViewRegistry>(new ViewRegistry()),
@@ -128,6 +130,8 @@ class MeterContext : public std::enable_shared_from_this<MeterContext>
 
   /**
    * Attaches a View to list of configured Views for this Meter context.
+   * @param instrument_selector The instrument selector for this view.
+   * @param meter_selector The meter selector for this view.
    * @param view The Views for this meter context. This
    * must not be a nullptr.
    *

sdk/include/opentelemetry/sdk/metrics/meter_provider.h

@@ -104,6 +104,8 @@ class OPENTELEMETRY_EXPORT MeterProvider final : public opentelemetry::metrics::
 
   /**
    * Attaches a View to list of configured Views for this Meter provider.
+   * @param instrument_selector The instrument selector for this view.
+   * @param meter_selector The meter selector for this view.
    * @param view The Views for this meter provider. This
    * must not be a nullptr.
    *

sdk/include/opentelemetry/sdk/resource/resource.h

@@ -38,7 +38,7 @@ class Resource
    *
    * The specification notes that if schema urls collide, the resulting
    * schema url is implementation-defined. In the C++ implementation, the
-   * schema url of @param other is picked.
+   * schema url of @p other is picked.
    *
    * @param other the Resource that will be merged with this.
    * @returns the newly merged Resource.
@@ -50,6 +50,7 @@ class Resource
    * Returns a newly created Resource with the specified attributes.
    * It adds (merge) SDK attributes and OTEL attributes before returning.
    * @param attributes for this resource
+   * @param schema_url The schema URL for this resource.
    * @returns the newly created Resource.
    */