diff --git a/.github/workflows/doxygen-tidy.yaml b/.github/workflows/doxygen-tidy.yaml new file mode 100644 index 0000000000..255d6a7991 --- /dev/null +++ b/.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 diff --git a/api/include/opentelemetry/logs/logger.h b/api/include/opentelemetry/logs/logger.h index 52f403b0ac..26663278cc 100644 --- a/api/include/opentelemetry/logs/logger.h +++ b/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, diff --git a/docs/public/Doxyfile b/docs/public/Doxyfile index a5d76ecba1..ec2bf9d04a 100644 --- a/docs/public/Doxyfile +++ b/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 diff --git a/docs/public/Doxyfile.lint b/docs/public/Doxyfile.lint new file mode 100644 index 0000000000..4dc16827d4 --- /dev/null +++ b/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 diff --git a/sdk/include/opentelemetry/sdk/logs/batch_log_record_processor.h b/sdk/include/opentelemetry/sdk/logs/batch_log_record_processor.h index 49398a1454..b423ed76b3 100644 --- a/sdk/include/opentelemetry/sdk/logs/batch_log_record_processor.h +++ b/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, diff --git a/sdk/include/opentelemetry/sdk/logs/logger.h b/sdk/include/opentelemetry/sdk/logs/logger.h index cb8ff6ab35..30e2b99db8 100644 --- a/sdk/include/opentelemetry/sdk/logs/logger.h +++ b/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, diff --git a/sdk/include/opentelemetry/sdk/logs/logger_provider.h b/sdk/include/opentelemetry/sdk/logs/logger_provider.h index ee5165ebd2..c0e04aecf6 100644 --- a/sdk/include/opentelemetry/sdk/logs/logger_provider.h +++ b/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 &&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 GetLogger( nostd::string_view logger_name, diff --git a/sdk/include/opentelemetry/sdk/metrics/meter_context.h b/sdk/include/opentelemetry/sdk/metrics/meter_context.h index 53f6298049..9ccd766565 100644 --- a/sdk/include/opentelemetry/sdk/metrics/meter_context.h +++ b/sdk/include/opentelemetry/sdk/metrics/meter_context.h @@ -58,6 +58,8 @@ class MeterContext : public std::enable_shared_from_this * 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 views = std::unique_ptr(new ViewRegistry()), @@ -128,6 +130,8 @@ class MeterContext : public std::enable_shared_from_this /** * 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. * diff --git a/sdk/include/opentelemetry/sdk/metrics/meter_provider.h b/sdk/include/opentelemetry/sdk/metrics/meter_provider.h index b2c5d36b18..a12f0d4cdf 100644 --- a/sdk/include/opentelemetry/sdk/metrics/meter_provider.h +++ b/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. * diff --git a/sdk/include/opentelemetry/sdk/resource/resource.h b/sdk/include/opentelemetry/sdk/resource/resource.h index b89e84649e..2706c4c01a 100644 --- a/sdk/include/opentelemetry/sdk/resource/resource.h +++ b/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. */ diff --git a/sdk/include/opentelemetry/sdk/trace/batch_span_processor.h b/sdk/include/opentelemetry/sdk/trace/batch_span_processor.h index 333c01df8a..38b0f38845 100644 --- a/sdk/include/opentelemetry/sdk/trace/batch_span_processor.h +++ b/sdk/include/opentelemetry/sdk/trace/batch_span_processor.h @@ -161,6 +161,7 @@ class BatchSpanProcessor : public SpanProcessor * any time * * @param notify_force_flush Sequence to indicate whether to notify force flush completion. + * @param exporter The span exporter instance that handles exporting spans to the backend. * @param synchronization_data Synchronization data to be notified. */ static void NotifyCompletion(uint64_t notify_force_flush, diff --git a/sdk/include/opentelemetry/sdk/trace/tracer_provider_factory.h b/sdk/include/opentelemetry/sdk/trace/tracer_provider_factory.h index 071a0551ca..85177f6565 100644 --- a/sdk/include/opentelemetry/sdk/trace/tracer_provider_factory.h +++ b/sdk/include/opentelemetry/sdk/trace/tracer_provider_factory.h @@ -23,7 +23,7 @@ namespace trace /** * Factory class for TracerProvider. - * See @ref TracerProvider. + * See @ref opentelemetry::trace::TracerProvider */ class OPENTELEMETRY_EXPORT TracerProviderFactory {