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

zurex · 2025-04-23T15:08:44Z

Changes

Update doc comments to compile with -Werror -Wdocumentation

This reduces the number of documentation warnings.
Enforcement in CI to be implemented separately.

netlify · 2025-04-23T15:09:01Z

✅ Deploy Preview for opentelemetry-cpp-api-docs canceled.

Name	Link
🔨 Latest commit	`5f26a2d`
🔍 Latest deploy log	https://app.netlify.com/projects/opentelemetry-cpp-api-docs/deploys/684053f104d673000812a054

codecov · 2025-04-23T15:38:16Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.89%. Comparing base (470f66b) to head (5f26a2d).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3375      +/-   ##
==========================================
+ Coverage   89.88%   89.89%   +0.02%     
==========================================
  Files         212      212              
  Lines        6942     6942              
==========================================
+ Hits         6239     6240       +1     
+ Misses        703      702       -1

Files with missing lines	Coverage Δ
.../include/opentelemetry/common/key_value_iterable.h	`100.00% <ø> (ø)`
...ude/opentelemetry/common/key_value_iterable_view.h	`100.00% <100.00%> (ø)`
...pi/include/opentelemetry/context/runtime_context.h	`97.60% <ø> (ø)`
api/include/opentelemetry/logs/event_logger.h	`90.00% <ø> (ø)`
...lemetry/exporters/memory/in_memory_span_exporter.h	`80.96% <100.00%> (ø)`
...rs/memory/src/in_memory_metric_exporter_factory.cc	`100.00% <ø> (ø)`
...clude/opentelemetry/sdk/common/atomic_unique_ptr.h	`100.00% <ø> (ø)`
sdk/include/opentelemetry/sdk/trace/recordable.h	`64.71% <ø> (ø)`
sdk/include/opentelemetry/sdk/trace/sampler.h	`100.00% <ø> (ø)`

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

api/include/opentelemetry/common/key_value_iterable.h

api/include/opentelemetry/common/attribute_value.h

CMakeLists.txt

sdk/include/opentelemetry/sdk/trace/recordable.h

api/include/opentelemetry/common/key_value_iterable_view.h

api/include/opentelemetry/semconv/url_attributes.h

psx95

Thanks for the PR!

Left some comments.

api/include/opentelemetry/context/runtime_context.h

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

api/include/opentelemetry/semconv/url_attributes.h

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

psx95 · 2025-04-26T01:26:03Z

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

@@ -265,7 +257,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


This looks incomplete ?

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

ThomsonTan · 2025-04-29T14:28:33Z

If the current format does break -Werror -WDocumention, it will also be good to add a CI pipeline with both option enabled, to ensure we have all the issues fixed and also guard future regression on it.

marcalff

Thanks for the cleanup.

See preliminary comments on generated code.

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

marcalff · 2025-04-29T15:19:20Z

[CI] Add a doxygen build #1647

marcalff

Thanks for the cleanup PR.

Please remove all changes done on generated code for semantic conventions.

If there are unresolved doxygen issues, this is fine, the CI will need to wait longer before enforcing -Wdocumentation in maintainer mode.

Cleanup work (speaking from experience with warning cleanup, include-what-you-use, ...) is typically done incrementally, so the fixes available here should be merged now, without waiting for the entire build to be fixed.

zurex · 2025-05-26T14:55:12Z

Thanks for the cleanup PR.

Please remove all changes done on generated code for semantic conventions.

If there are unresolved doxygen issues, this is fine, the CI will need to wait longer before enforcing -Wdocumentation in maintainer mode.

Cleanup work (speaking from experience with warning cleanup, include-what-you-use, ...) is typically done incrementally, so the fixes available here should be merged now, without waiting for the entire build to be fixed.

Thanks for suggestions, kind of busy these days :(.

…lemetry-cpp into fix/doc_comment_api

marcalff · 2025-05-26T16:15:47Z

Weaver code generation breaks HTML links. weaver#751

marcalff

LGTM, thanks for the fix.

See minor cleanup.

.clang-format

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

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

…ory_span_exporter.h Co-authored-by: Marc Alff <[email protected]>

Co-authored-by: Marc Alff <[email protected]>

psx95

Thanks for addressing the comments!
Overall it looks good, just a few minor nits remaining.

psx95 · 2025-06-02T21:08:03Z

api/include/opentelemetry/common/key_value_iterable.h

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


Nit: Technically, the @param should still be there.

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

Update all the doc comments and add WDocumention

4f5255a

zurex requested a review from a team as a code owner April 23, 2025 15:08

zurex changed the title ~~Update all the doc comments and add WDocumention~~ [DOC] Update all the doc comments and add WDocumention Apr 23, 2025

Merge branch 'main' into fix/doc_comment_api

5610dbc

zurex added 2 commits April 23, 2025 16:51

Fix the doc comments in http_operation_curl.h

6402c14

Merge remote changes

a45b644

lalitb reviewed Apr 23, 2025

View reviewed changes

api/include/opentelemetry/common/key_value_iterable.h Outdated Show resolved Hide resolved

lalitb reviewed Apr 23, 2025

View reviewed changes

api/include/opentelemetry/common/attribute_value.h Outdated Show resolved Hide resolved

lalitb and others added 3 commits April 23, 2025 21:45

Merge branch 'main' into fix/doc_comment_api

15c3fd6

Fix the doc comment issues in semconv

e3c83f5

Add more details for AttributeValue warnning

7a210ec

dbarker reviewed Apr 24, 2025

View reviewed changes

CMakeLists.txt Outdated Show resolved Hide resolved

dbarker reviewed Apr 24, 2025

View reviewed changes

sdk/include/opentelemetry/sdk/trace/recordable.h Outdated Show resolved Hide resolved

dbarker reviewed Apr 24, 2025

View reviewed changes

api/include/opentelemetry/common/key_value_iterable_view.h Outdated Show resolved Hide resolved

zurex and others added 2 commits April 24, 2025 16:30

Fix the doc issues in url_atteibutes.h

78d6787

Merge branch 'main' into fix/doc_comment_api

6a91bc4

ThomsonTan reviewed Apr 24, 2025

View reviewed changes

api/include/opentelemetry/semconv/url_attributes.h Outdated Show resolved Hide resolved

psx95 requested changes Apr 26, 2025

View reviewed changes

zurex and others added 2 commits April 26, 2025 17:47

Merge branch 'main' into fix/doc_comment_api

dad87ba

Merge branch 'main' into fix/doc_comment_api

210c863

marcalff reviewed Apr 29, 2025

View reviewed changes

api/include/opentelemetry/semconv/incubating/process_attributes.h Outdated Show resolved Hide resolved

zurex and others added 5 commits May 6, 2025 14:57

Fix the doc comments

e30863f

Fix the comments under api

531ae64

Fix the format issue

0c0f2f7

Merge branch 'main' into fix/doc_comment_api

00a4b13

Merge branch 'main' into fix/doc_comment_api

2e07267

Merge branch 'main' into fix/doc_comment_api

79cc519

marcalff requested changes May 26, 2025

View reviewed changes

zurex added 4 commits May 26, 2025 15:12

Revert changes in semconv

9296f1f

Merge branch 'fix/doc_comment_api' of https://github.com/zurex/opente…

6f41459

…lemetry-cpp into fix/doc_comment_api

Remove bad checkin

32a7861

Fix the format

c682d1a

zurex added 2 commits May 26, 2025 16:36

Remove doc check under maintainer mode

7c5e5c3

Fix eof

9ef149a

marcalff approved these changes May 27, 2025

View reviewed changes

.clang-format Outdated Show resolved Hide resolved

Revert clang-format

37c8ff8

zurex changed the title ~~[DOC] Update all the doc comments and add WDocumention~~ [DOC] Update all the doc comments to pass -WDocumention check May 28, 2025

zurex added 2 commits May 29, 2025 00:31

Merge branch 'open-telemetry:main' into fix/doc_comment_api

fbba434

Address the review comments

ae8ed3a

marcalff reviewed May 28, 2025

View reviewed changes

exporters/memory/include/opentelemetry/exporters/memory/in_memory_span_exporter.h Outdated Show resolved Hide resolved

marcalff reviewed May 28, 2025

View reviewed changes

sdk/include/opentelemetry/sdk/common/atomic_unique_ptr.h Outdated Show resolved Hide resolved

zurex and others added 3 commits May 29, 2025 10:09

Update exporters/memory/include/opentelemetry/exporters/memory/in_mem…

54787c1

…ory_span_exporter.h Co-authored-by: Marc Alff <[email protected]>

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

0979723

Co-authored-by: Marc Alff <[email protected]>

Merge branch 'main' into fix/doc_comment_api

b4fcb74

zurex requested a review from psx95 June 1, 2025 09:07

Merge branch 'main' into fix/doc_comment_api

d56e527

psx95 approved these changes Jun 2, 2025

View reviewed changes

Merge branch 'main' into fix/doc_comment_api

5f26a2d

marcalff changed the title ~~[DOC] Update all the doc comments to pass -WDocumention check~~ [DOC] Update doc comments to pass -WDocumention check Jun 5, 2025

marcalff merged commit d64b653 into open-telemetry:main Jun 5, 2025
67 checks passed

malkia added a commit to malkia/opentelemetry-cpp that referenced this pull request Jun 5, 2025

Merge pull request #334 from open-telemetry/main

bb69806

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

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

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

Conversation

zurex commented Apr 23, 2025 • edited by marcalff Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

netlify bot commented Apr 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for opentelemetry-cpp-api-docs canceled.

Uh oh!

codecov bot commented Apr 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

psx95 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

psx95 Apr 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ThomsonTan commented Apr 29, 2025

Uh oh!

marcalff left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marcalff commented Apr 29, 2025

Uh oh!

marcalff left a comment

Choose a reason for hiding this comment

Uh oh!

zurex commented May 26, 2025

Uh oh!

marcalff commented May 26, 2025

Uh oh!

marcalff left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

psx95 left a comment

Choose a reason for hiding this comment

Uh oh!

psx95 Jun 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

zurex commented Apr 23, 2025 •

edited by marcalff

Loading

netlify bot commented Apr 23, 2025 •

edited

Loading

codecov bot commented Apr 23, 2025 •

edited

Loading