Clang Flag: -Wdocumentation / -Wno-documentation

The Clang compiler supports a wide range of flags that can be used to customize the compilation process. Among these, the -Wdocumentation flag plays a crucial role for developers who are attentive to the quality and correctness of their code documentation. When activated, this flag triggers warnings related to documentation issues within the source code. These warnings cover a plethora of potential documentation pitfalls, including but not limited to misuse of documentation commands in comments, mismatches between documented parameters or template parameters and their corresponding declarations, documentation attached to inappropriate declarations, duplications in parameter documentation, and issues specific to HTML tags within documentation blocks. Activating -Wdocumentation is particularly beneficial for maintaining high standards of code documentation, ensuring that documentation is accurately aligned with the code it describes, and adhering to best practices in documentation syntax and semantics. Given that -Wdocumentation is not active by default, developers must explicitly enable it to take advantage of its checks. This approach allows developers to opt-in to more stringent documentation checks at their discretion, without imposing additional overhead on those who may not require such detailed documentation analysis. The flag's functionality is complemented by its counterpart, the -Wno-documentation flag, which can be used to suppress these documentation-related warnings. However, in the context of this article, -Wno-documentation has no explicitly listed active elements, indicating that the focus is on encouraging developers to enable and heed the guidance of -Wdocumentation warnings for improving their code documentation practices. Overall, the -Wdocumentation flag offers a powerful tool for developers seeking to enhance the quality, accuracy, and usefulness of their code documentation, contributing to better maintained, more understandable, and more easily navigable codebases.

AI Generated

Subroups

• -Wdocumentation-html (4 elements)
• -Wdocumentation-deprecated-sync (1 element)

Warnings/Remarks

Default Active (Deactivate with -Wno-documentation)

None

Default Inactive (Activate with -Wdocumentation)

warn_doc_api_container_decl_mismatch	warning: ' \ @ class interface protocol struct union ' command should not be used in a comment attached to a non- class interface protocol struct union declaration
warn_doc_block_command_duplicate	warning: duplicated command ' \ @ B'
warn_doc_block_command_empty_paragraph	warning: empty paragraph passed to ' \ @ B' command
warn_doc_container_decl_mismatch	warning: ' \ @ classdesign coclass dependency helper helperclass helps instancesize ownership performance security superclass ' command should not be used in a comment attached to a non-container declaration
warn_doc_function_method_decl_mismatch	warning: ' \ @ function functiongroup method methodgroup callback ' command should be used in a comment attached to a function a function an Objective-C method an Objective-C method a pointer to function declaration
warn_doc_html_start_tag_expected_ident_or_greater	warning: HTML start tag prematurely ended, expected attribute name or '>'
warn_doc_html_start_tag_expected_quoted_string	warning: expected quoted string after equals sign
warn_doc_inline_command_not_enough_arguments	warning: ' \ @ B' command has no C word argumentC, expected D
warn_doc_param_duplicate	warning: parameter 'A' is already documented
warn_doc_param_invalid_direction	warning: unrecognized parameter passing direction, valid directions are '[in]', '[out]' and '[in,out]'
warn_doc_param_not_attached_to_a_function_decl	warning: ' \ @ param' command used in a comment that is not attached to a function declaration
warn_doc_param_not_found	warning: parameter 'A' not found in the function declaration
warn_doc_returns_attached_to_a_void_function	warning: ' \ @ B' command used in a comment that is attached to a function returning void constructor destructor method returning void
warn_doc_returns_not_attached_to_a_function_decl	warning: ' \ @ B' command used in a comment that is not attached to a function or method declaration
warn_doc_tparam_duplicate	warning: template parameter 'A' is already documented
warn_doc_tparam_not_attached_to_a_template_decl	warning: ' \ @ tparam' command used in a comment that is not attached to a template declaration
warn_doc_tparam_not_found	warning: template parameter 'A' not found in the template declaration
warn_not_a_doxygen_trailing_member_comment	warning: not a Doxygen trailing comment
warn_splice_in_doxygen_comment	warning: line splicing in Doxygen comments are not supported
warn_verbatim_block_end_without_start	warning: ' \ @ B' command does not terminate a verbatim text block
warn_doc_html_end_forbidden	warning: HTML end tag 'A' is forbidden
warn_doc_html_end_unbalanced	warning: HTML end tag does not match any start tag
warn_doc_html_missing_end_tag	warning: HTML tag 'A' requires an end tag
warn_doc_html_start_end_mismatch	warning: HTML start tag 'A' closed by 'B'
warn_doc_deprecated_not_sync	warning: declaration is marked with ' \ @ deprecated' command but does not have a deprecation attribute