Skip to content

CXX-3108 Address missing enum member documentation Doxgyen warnings #1211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 19, 2024

Conversation

eramongodb
Copy link
Contributor

Addresses CXX-3108. Followup to #1185.

Sets WARN_IF_UNDOC_ENUM_VAL = YES (deferred by #1185), which enables warnings for undocumented enumerators.

This revealed several enumerators in mongocxx::v_noabi::error_code which were incorrectly using // instead of ///.

Additionally, the enumerators of the following enumerations were completely undocumented (descriptions may have been present in the enumeration's documentation, but this of course does not generate enumerator tables or enable Doxygen references):

  • mongocxx::v_noabi::log_level
  • mongocxx::v_noabi::options::server_api::version
  • mongocxx::v_noabi::read_concern::level
  • mongocxx::v_noabi::write_concern::level
  • mongocxx::v_noabi::validation_criteria::validation_level
  • mongocxx::v_noabi::validation_criteria::validation_action

A drive-by documentation style improvement uses @li for @see items for better formatting as well as Markdown-style titled links.

The choice between /// vs. ///< is simply: if ///< results in line-wrapping for one or more enumerators, use /// instead.

image

image

image

@eramongodb eramongodb self-assigned this Sep 18, 2024
@eramongodb
Copy link
Contributor Author

Clang's -Wdocumentation appears to emit false-positives for a sequence of @see @<command>, incorrectly interpreting it as an empty paragraph. Converted @li patterns to using Markdown list syntax instead.

Additionally updated clang-format rules to avoid wrapping list items as is often done for @see blocks.

@eramongodb eramongodb merged commit ff7e7bd into mongodb:master Sep 19, 2024
71 of 79 checks passed
@eramongodb eramongodb deleted the cxx-3108 branch September 19, 2024 16:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants