Author: Piotr Zegar Date: 2023-06-26T18:20:39Z New Revision: 9aaf3cf9bfe803d0a32709aa160951a6675b5926
URL: https://github.com/llvm/llvm-project/commit/9aaf3cf9bfe803d0a32709aa160951a6675b5926 DIFF: https://github.com/llvm/llvm-project/commit/9aaf3cf9bfe803d0a32709aa160951a6675b5926.diff LOG: [clang-tidy][NFC] Repharse a lite bit documentation for misc-header-include-cycle check Change documentation, to avoid some duplication, and make it sound beter. Added: Modified: clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst Removed: ################################################################################ diff --git a/clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst b/clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst index 622dc784f3c61..de08f0d0bea07 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst @@ -21,42 +21,44 @@ Check detects cyclic ``#include`` dependencies between user-defined headers. // Include chain: A->B->C->A -Header files are a crucial part of many C++ programs, as they provide a way to -organize declarations and definitions that are shared across multiple source -files. However, header files can also create problems when they become entangled +Header files are a crucial part of many C++ programs as they provide a way to +organize declarations and definitions shared across multiple source files. +However, header files can also create problems when they become entangled in complex dependency cycles. Such cycles can cause issues with compilation times, unnecessary rebuilds, and make it harder to understand the overall structure of the code. -To address these issues, this check has been developed. This check is designed -to detect cyclic dependencies between header files, also known as -"include cycles". An include cycle occurs when a header file `A` includes a -header file `B`, and header file `B` (or any later included header file in the -chain) includes back header file `A`, leading to a circular dependency cycle. - -This check operates at the preprocessor level and analyzes user-defined headers -and their dependencies. It focuses specifically on detecting include cycles, -and ignores other types or function dependencies. This allows it to provide a -specialized analysis that is focused on identifying and preventing issues -related to header file organization. - -The benefits of using this check are numerous. By detecting include cycles early -in the development process, developers can identify and resolve these issues -before they become more diff icult and time-consuming to fix. This can lead to -faster compile times, improved code quality, and a more maintainable codebase -overall. Additionally, by ensuring that header files are organized in a way that -avoids cyclic dependencies, developers can make their code easier to understand -and modify over time. - -It's worth noting that this tool only analyzes user-defined headers and their -dependencies, excluding system includes such as standard library headers and -third-party library headers. System includes are usually well-designed and free -of include cycles, and ignoring them helps to focus on potential issues within -the project's own codebase. This limitation doesn't diminish the tool's ability -to detect ``#include`` cycles within the analyzed code. As with any tool, -developers should use their judgment when evaluating the warnings produced by -the check and be prepared to make exceptions or modifications to their code as -needed. +To address these issues, a check has been developed to detect cyclic +dependencies between header files, also known as "include cycles". +An include cycle occurs when a header file `A` includes header file `B`, +and `B` (or any subsequent included header file) includes back header file `A`, +resulting in a circular dependency cycle. + +This check operates at the preprocessor level and specifically analyzes +user-defined headers and their dependencies. It focuses solely on detecting +include cycles while disregarding other types or function dependencies. +This specialized analysis helps identify and prevent issues related to header +file organization. + +By detecting include cycles early in the development process, developers can +identify and resolve these issues before they become more diff icult and +time-consuming to fix. This can lead to faster compile times, improved code +quality, and a more maintainable codebase overall. Additionally, by ensuring +that header files are organized in a way that avoids cyclic dependencies, +developers can make their code easier to understand and modify over time. + +It's worth noting that only user-defined headers their dependencies are analyzed, +System includes such as standard library headers and third-party library headers +are excluded. System includes are usually well-designed and free of include +cycles, and ignoring them helps to focus on potential issues within the +project's own codebase. This limitation doesn't diminish the ability to detect +``#include`` cycles within the analyzed code. + +Developers should carefully review any warnings or feedback provided by this +solution. While the analysis aims to identify and prevent include cycles, there +may be situations where exceptions or modifications are necessary. It's +important to exercise judgment and consider the specific context of the codebase +when making adjustments. Options ------- _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
