Skip to content

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.

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