https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/222507
>From 392fc35c78f3610a9e6a2a0c96710e98a7364165 Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Wed, 9 Sep 2026 23:00:36 +0000 Subject: [PATCH 1/4] [docs] Replace clang.llvm.org/docs links with Sphinx links Use Sphinx document and option roles or project-relative links for links within the Clang documentation. Repair stale generated-document fragments found while validating the replacements. This ensures that standalone documentation builds are self-contained, although cross-project links (Clang->LLVM) typically go via absolute llvm.org hrefs. Part of #214861 Assisted-by: Codex --- clang/docs/AllocToken.md | 4 ++-- clang/docs/ClangLinkerWrapper.md | 2 +- clang/docs/ClangOffloadBundler.md | 2 +- clang/docs/ClangTransformerTutorial.md | 2 +- clang/docs/ControlFlowIntegrity.md | 2 +- clang/docs/ControlFlowIntegrityDesign.md | 2 +- clang/docs/InternalsManual.md | 2 +- clang/docs/IntroductionToTheClangAST.md | 3 +-- clang/docs/LanguageExtensions.md | 10 +++++----- clang/docs/LibASTImporter.md | 2 +- clang/docs/LifetimeSafety.md | 12 ++++++------ clang/docs/SafeBuffers.md | 7 +++---- .../user-docs/SummaryExtraction.md | 3 +-- clang/docs/WarningSuppressionMappings.md | 3 +-- clang/docs/analyzer/checkers.md | 8 ++++---- clang/docs/analyzer/user-docs/Annotations.md | 6 +++--- 16 files changed, 33 insertions(+), 37 deletions(-) diff --git a/clang/docs/AllocToken.md b/clang/docs/AllocToken.md index b3a72ed480097..96aa05c045b24 100644 --- a/clang/docs/AllocToken.md +++ b/clang/docs/AllocToken.md @@ -166,8 +166,8 @@ the allocation call the wrapper returns, which is then instrumented normally. Wrappers that are not inlined still require `-fsanitize-alloc-token-extended`. -[malloc-attribute]: https://clang.llvm.org/docs/AttributeReference.html#malloc -[alloc-size-attribute]: https://clang.llvm.org/docs/AttributeReference.html#alloc-size +[malloc-attribute]: project:AttributeReference.md#malloc +[alloc-size-attribute]: project:AttributeReference.md#alloc-size ### Disabling Instrumentation diff --git a/clang/docs/ClangLinkerWrapper.md b/clang/docs/ClangLinkerWrapper.md index 081bfce2ea359..4052304e81946 100644 --- a/clang/docs/ClangLinkerWrapper.md +++ b/clang/docs/ClangLinkerWrapper.md @@ -87,7 +87,7 @@ cause it be linked with any other device code with the same target triple. The linker wrapper performs a lot of steps internally, such as input matching, symbol resolution, and image registration. This makes it difficult to debug in some scenarios. The behavior of the linker-wrapper is controlled mostly through -metadata, described in [clang documentation](https://clang.llvm.org/docs/OffloadingDesign.html). +metadata, described in {doc}`clang documentation <OffloadingDesign>`. The individual tool invocations the wrapper performs can be printed with the `--wrapper-verbose` flag, and the intermediate files they operate on can be diff --git a/clang/docs/ClangOffloadBundler.md b/clang/docs/ClangOffloadBundler.md index 0dd93849eb275..d9d1d263d1e1c 100644 --- a/clang/docs/ClangOffloadBundler.md +++ b/clang/docs/ClangOffloadBundler.md @@ -279,7 +279,7 @@ without differentiation based on offload kind. **target-triple** -: The target triple of the code object. See [Target Triple](https://clang.llvm.org/docs/CrossCompilation.html#target-triple). +: The target triple of the code object. See [Target Triple](project:CrossCompilation.md#target-triple). LLVM target triples can be with or without the optional environment field: diff --git a/clang/docs/ClangTransformerTutorial.md b/clang/docs/ClangTransformerTutorial.md index eba7c5e6b6085..381969ea3a8cf 100644 --- a/clang/docs/ClangTransformerTutorial.md +++ b/clang/docs/ClangTransformerTutorial.md @@ -367,7 +367,7 @@ introductions on clang's site: - {doc}`Introduction to the Clang AST <IntroductionToTheClangAST>` - {doc}`Matching the Clang AST <LibASTMatchers>` -- [AST Matcher Reference](https://clang.llvm.org/docs/LibASTMatchersReference.html) +- [AST Matcher Reference](LibASTMatchersReference.html) :::{rubric} Footnotes ::: diff --git a/clang/docs/ControlFlowIntegrity.md b/clang/docs/ControlFlowIntegrity.md index 045b70a4e23b3..c25a27fd910c5 100644 --- a/clang/docs/ControlFlowIntegrity.md +++ b/clang/docs/ControlFlowIntegrity.md @@ -39,7 +39,7 @@ CFI checks for classes without visibility attributes. Most users will want to specify `-fvisibility=hidden`, which enables CFI checks for such classes. When using `-fsanitize=cfi*` with `-flto=thin`, it is recommended -to reduce link times by passing [-funique-source-file-names](https://clang.llvm.org/docs/UsersManual.html#cmdoption-f-no-unique-source-file-names), provided +to reduce link times by passing {option}`-funique-source-file-names <-f[no-]unique-source-file-names>`, provided that your program is compatible with it. Experimental support for {ref}`cross-DSO control flow integrity diff --git a/clang/docs/ControlFlowIntegrityDesign.md b/clang/docs/ControlFlowIntegrityDesign.md index 0885b7a7b5891..4dad111116acb 100644 --- a/clang/docs/ControlFlowIntegrityDesign.md +++ b/clang/docs/ControlFlowIntegrityDesign.md @@ -780,5 +780,5 @@ ability to protect against invalid casts between polymorphic types. [globalsplit]: https://github.com/llvm/llvm-project/blob/main/llvm/lib/Transforms/IPO/GlobalSplit.cpp [intel cet]: https://software.intel.com/en-us/blogs/2016/06/09/intel-release-new-technology-specifications-protect-rop-attacks [rfg]: https://xlab.tencent.com/en/2016/11/02/return-flow-guard -[safestack]: https://clang.llvm.org/docs/SafeStack.html +[safestack]: project:SafeStack.md [type metadata]: https://llvm.org/docs/TypeMetadata.html diff --git a/clang/docs/InternalsManual.md b/clang/docs/InternalsManual.md index 0d9ee745927aa..0fef2920fee99 100644 --- a/clang/docs/InternalsManual.md +++ b/clang/docs/InternalsManual.md @@ -2919,7 +2919,7 @@ allowing the programmer to pass semantic information along to the compiler for various uses. For example, attributes may be used to alter the code generation for a program construct, or to provide extra semantic information for static analysis. This document explains how to add a custom attribute to Clang. -Documentation on existing attributes can be found [here](https://clang.llvm.org/docs/AttributeReference.html). +Documentation on existing attributes can be found {doc}`here <AttributeReference>`. #### Attribute Basics diff --git a/clang/docs/IntroductionToTheClangAST.md b/clang/docs/IntroductionToTheClangAST.md index 56431b9ee5fec..10831c91579b3 100644 --- a/clang/docs/IntroductionToTheClangAST.md +++ b/clang/docs/IntroductionToTheClangAST.md @@ -109,7 +109,7 @@ node - this information has to be encoded for each specific node type. This algorithm is encoded in the [RecursiveASTVisitor](https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html). See the [RecursiveASTVisitor -tutorial](https://clang.llvm.org/docs/RAVFrontendAction.html). +tutorial](project:RAVFrontendAction.rst). The two most basic nodes in the Clang AST are statements ([Stmt](https://clang.llvm.org/doxygen/classclang_1_1Stmt.html)) and @@ -118,4 +118,3 @@ declarations that expressions ([Expr](https://clang.llvm.org/doxygen/classclang_1_1Expr.html)) are also statements in Clang's AST. - diff --git a/clang/docs/LanguageExtensions.md b/clang/docs/LanguageExtensions.md index bd47b18da2481..508d0e2fa3003 100644 --- a/clang/docs/LanguageExtensions.md +++ b/clang/docs/LanguageExtensions.md @@ -1735,7 +1735,7 @@ mode. Use `__has_feature(modules)` to determine if Modules have been enabled. For example, compiling code with `-fmodules` enables the use of Modules. -More information can be found [here](https://clang.llvm.org/docs/Modules.html). +More information can be found {doc}`here <Modules>`. ## Language Extensions Back-ported to Previous Standards @@ -2582,7 +2582,7 @@ and `-respondsToSelector:` or `+instancesRespondToSelector:` for Objective-C methods. If such a check was missed, the program would compile fine, run fine on newer systems, but crash on older systems. -As of LLVM 5.0, `-Wunguarded-availability` uses the [availability attributes](https://clang.llvm.org/docs/AttributeReference.html#availability) together +As of LLVM 5.0, `-Wunguarded-availability` uses the [availability attributes](project:AttributeReference.md#availability) together with the new `@available()` keyword to assist with this issue. When a method that's introduced in the OS newer than the target OS is called, a -Wunguarded-availability warning is emitted if that call is not guarded: @@ -2624,7 +2624,7 @@ void my_fun(NSSomeClass* var) { ``` If the caller of `my_fun()` already checks that `my_fun()` is only called -on 10.12, then add an [availability attribute](https://clang.llvm.org/docs/AttributeReference.html#availability) to it, +on 10.12, then add an [availability attribute](project:AttributeReference.md#availability) to it, which will also suppress the warning and require that calls to my_fun() are checked: @@ -4715,7 +4715,7 @@ The effect of passing some other value to `__builtin_flt_rounds` is implementation-defined. `__builtin_set_flt_rounds` is currently only supported to work on x86, x86_64, powerpc, powerpc64, Arm and AArch64 targets. These builtins read and modify the floating-point environment, which is not always allowed and may -have unexpected behavior. Please see the section on [Accessing the floating point environment](https://clang.llvm.org/docs/UsersManual.html#accessing-the-floating-point-environment) for more information. +have unexpected behavior. Please see the section on [Accessing the floating point environment](project:UsersManual.md#accessing-the-floating-point-environment) for more information. ### String builtins @@ -6623,7 +6623,7 @@ more information about subobjects to be determined, so the `type & 1 == 1` case will often give imprecise results when used across a function call boundary even when optimization is enabled. -[The pass_object_size and pass_dynamic_object_size attributes](https://clang.llvm.org/docs/AttributeReference.html#pass-object-size-pass-dynamic-object-size) +[The pass_object_size and pass_dynamic_object_size attributes](project:AttributeReference.md#pass-object-size-pass-dynamic-object-size) can be used to invisibly pass the object size for a pointer parameter alongside the pointer in a function call. This allows more precise object sizes to be determined both when building without optimizations and in the `type & 1 == 1` diff --git a/clang/docs/LibASTImporter.md b/clang/docs/LibASTImporter.md index 2ccb05ba33b1c..c0be3c0c28c0d 100644 --- a/clang/docs/LibASTImporter.md +++ b/clang/docs/LibASTImporter.md @@ -6,7 +6,7 @@ It imports nodes of an `ASTContext` into another `ASTContext`. In this document, we assume basic knowledge about the Clang AST. See the {doc}`Introduction to the Clang AST <IntroductionToTheClangAST>` if you want to learn more about how the AST is structured. -Knowledge about {doc}`matching the Clang AST <LibASTMatchers>` and the [reference for the matchers](https://clang.llvm.org/docs/LibASTMatchersReference.html) are also useful. +Knowledge about {doc}`matching the Clang AST <LibASTMatchers>` and the [reference for the matchers](LibASTMatchersReference.html) are also useful. ## Introduction diff --git a/clang/docs/LifetimeSafety.md b/clang/docs/LifetimeSafety.md index dcf206547643d..a7a964af7c6f2 100644 --- a/clang/docs/LifetimeSafety.md +++ b/clang/docs/LifetimeSafety.md @@ -22,8 +22,8 @@ This is compile-time analysis; there is no run-time overhead. It tracks pointer validity through intra-procedural data-flow analysis. While it does not require lifetime annotations to get started, in their absence, the analysis treats function calls optimistically, assuming no lifetime effects, thereby potentially missing dangling pointer issues. As more functions are annotated -with attributes like [clang::lifetimebound](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound), [gsl::Owner](https://clang.llvm.org/docs/AttributeReference.html#gsl-owner), and -[gsl::Pointer](https://clang.llvm.org/docs/AttributeReference.html#gsl-pointer), the analysis can see through these lifetime contracts and enforce +with attributes like [clang::lifetimebound](project:AttributeReference.md#lifetimebound), [gsl::Owner](project:AttributeReference.md#owner), and +[gsl::Pointer](project:AttributeReference.md#pointer), the analysis can see through these lifetime contracts and enforce lifetime safety at call sites with higher accuracy. This approach supports gradual adoption in existing codebases. @@ -122,8 +122,8 @@ void test() { Without these annotations, the analysis may not be able to determine whether a type is owning or borrowing, which can affect analysis precision. For more details on these attributes, see the Clang attribute reference for -[gsl::Owner](https://clang.llvm.org/docs/AttributeReference.html#gsl-owner) and -[gsl::Pointer](https://clang.llvm.org/docs/AttributeReference.html#gsl-pointer). +[gsl::Owner](project:AttributeReference.md#owner) and +[gsl::Pointer](project:AttributeReference.md#pointer). :::{note} Types with mixed ownership semantics (owning some data while holding views to @@ -191,7 +191,7 @@ void test() { } ``` -For more details, see [lifetimebound](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound). +For more details, see [lifetimebound](project:AttributeReference.md#lifetimebound). ### NoEscape @@ -203,7 +203,7 @@ parameter to escape its scope, for example, by returning it or assigning it to a field or global variable. This is useful for parameters passed to callbacks or visitors that are only used during the call and not stored. -For more details, see [noescape](https://clang.llvm.org/docs/AttributeReference.html#noescape). +For more details, see [noescape](project:AttributeReference.md#noescape). ## Checks Performed diff --git a/clang/docs/SafeBuffers.md b/clang/docs/SafeBuffers.md index cc7d74ed37efb..7159581bc18fc 100644 --- a/clang/docs/SafeBuffers.md +++ b/clang/docs/SafeBuffers.md @@ -61,7 +61,7 @@ acting as "hardened custom containers" to replace raw pointers. However, such approach would be very unergonomic in C, and safety guarantees will be lower due to lack of good encapsulation technology. A better approach to bounds safety for non-C++ programs, -[-fbounds-safety](https://clang.llvm.org/docs/BoundsSafety.html), +{doc}`-fbounds-safety <BoundsSafety>`, is currently in development. Technically, safety guarantees cannot be provided without hardening @@ -321,7 +321,7 @@ int get_last_element(int *pointer, size_t size) { } ``` -This behavior is analogous to `#pragma clang diagnostic` ([documentation](https://clang.llvm.org/docs/UsersManual.html#controlling-diagnostics-via-pragmas)) +This behavior is analogous to `#pragma clang diagnostic` ([documentation](project:UsersManual.md#controlling-diagnostics-via-pragmas)) However, `#pragma clang unsafe_buffer_usage` is specialized and recommended over `#pragma clang diagnostic` for a number of technical and non-technical reasons. Most importantly, `#pragma clang unsafe_buffer_usage` is more @@ -391,7 +391,7 @@ passed into the wrapper is correct.** ### Flag bounds information discontinuities with `[[clang::unsafe_buffer_usage]]` The clang attribute `[[clang::unsafe_buffer_usage]]` -([attribute documentation](https://clang.llvm.org/docs/AttributeReference.html#unsafe-buffer-usage)) +([attribute documentation](project:AttributeReference.md#unsafe-buffer-usage)) allows the user to annotate various objects, such as functions or member variables, as incompatible with the Safe Buffers programming model. You are encouraged to do that for arbitrary reasons, but typically the main @@ -587,4 +587,3 @@ significantly fewer warnings. It will also need to bypass `#pragma clang unsafe_buffer_usage` suppressions and "see through" unsafe wrappers such as `unsafe_forge_span` -- something that the static analyzer is naturally capable of doing. - diff --git a/clang/docs/ScalableStaticAnalysis/user-docs/SummaryExtraction.md b/clang/docs/ScalableStaticAnalysis/user-docs/SummaryExtraction.md index 50d5ccf510822..e6dd69106e36e 100644 --- a/clang/docs/ScalableStaticAnalysis/user-docs/SummaryExtraction.md +++ b/clang/docs/ScalableStaticAnalysis/user-docs/SummaryExtraction.md @@ -32,5 +32,4 @@ or just happens to have an error, then the error is forwarded as a `scalable-sta These errors can be downgraded into warnings using `-Wno-error=scalable-static-analysis-framework`. These errors can be completely suppressed using `-Wno-scalable-static-analysis-framework`. -See the [diagnostic flags](https://clang.llvm.org/docs/DiagnosticsReference.html#wscalable-static-analysis-framework) for the full list of diagnostics controlled by `-Wscalable-static-analysis-framework`. - +See the [diagnostic flags](project:../../DiagnosticsReference.md#wscalable-static-analysis-framework) for the full list of diagnostics controlled by `-Wscalable-static-analysis-framework`. diff --git a/clang/docs/WarningSuppressionMappings.md b/clang/docs/WarningSuppressionMappings.md index 2c6ce42f7c668..e493f23e469b4 100644 --- a/clang/docs/WarningSuppressionMappings.md +++ b/clang/docs/WarningSuppressionMappings.md @@ -26,7 +26,7 @@ flag. Note that this mechanism won't enable any diagnostics on its own. Users should still turn on warnings in their compilations with explicit `-Wfoo` flags. -[Controlling diagnostics pragmas](https://clang.llvm.org/docs/UsersManual.html#controlling-diagnostics-via-pragmas) +[Controlling diagnostics pragmas](project:UsersManual.md#controlling-diagnostics-via-pragmas) take precedence over suppression mappings. Ensuring code author's explicit intent is always preserved. @@ -86,4 +86,3 @@ src:*foo/*=emit # Only suppress for sources under bar/. src:*bar/* ``` - diff --git a/clang/docs/analyzer/checkers.md b/clang/docs/analyzer/checkers.md index e81aa07b59ae4..e504e61968a5b 100644 --- a/clang/docs/analyzer/checkers.md +++ b/clang/docs/analyzer/checkers.md @@ -197,7 +197,7 @@ void test() { Null pointer dereferences of pointers with address spaces are not always defined as error. Specifically on x86/x86-64 target if the pointer address space is 256 (x86 GS Segment), 257 (x86 FS Segment), or 258 (x86 SS Segment), a null -dereference is not defined as error. See [X86/X86-64 Language Extensions](https://clang.llvm.org/docs/LanguageExtensions.html#memory-references-to-specified-segments) +dereference is not defined as error. See [X86/X86-64 Language Extensions](project:../LanguageExtensions.md#memory-references-to-specified-segments) for reference. If the analyzer option `suppress-dereferences-from-any-address-space` is set @@ -808,7 +808,7 @@ This checker does not accept the coding pattern where an enum type is used to store combinations of flag values. Such enums should be annotated with the `__attribute__((flag_enum))` or by the `[[clang::flag_enum]]` attribute to signal this intent. Refer to the -[documentation](https://clang.llvm.org/docs/AttributeReference.html#flag-enum) +[documentation](project:../AttributeReference.md#flag-enum) of this Clang attribute. ```cpp @@ -901,7 +901,7 @@ arguments -- even if there is no such call in the codebase. This design rule is dictated by the SEI CERT rule [EXP47-C](https://wiki.sei.cmu.edu/confluence/display/c/EXP47-C.+Do+not+call+va_arg+with+an+argument+of+the+incorrect+type), which describes several issues related to the use of `va_arg()`. (The problem reported by this checker is shown in the second code example; the first, -unrelated code example is covered by the clang diagnostic [-Wvarargs](https://clang.llvm.org/docs/DiagnosticsReference.html#wvarargs).) +unrelated code example is covered by the clang diagnostic [-Wvarargs](project:../DiagnosticsReference.md#wvarargs).) ```cpp // This function expects a list of variadic arguments terminated by a NULL pointer. @@ -3357,7 +3357,7 @@ int *direct_return() { The attribute states that the returned value is dangling after the lifetime of the annotated parameter, or of the implicit object argument, has ended. -Refer to the [documentation](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound) +Refer to the [documentation](project:../AttributeReference.md#lifetimebound) of this Clang attribute. ```cpp diff --git a/clang/docs/analyzer/user-docs/Annotations.md b/clang/docs/analyzer/user-docs/Annotations.md index ce2f42fa1920f..11feb69ea00f8 100644 --- a/clang/docs/analyzer/user-docs/Annotations.md +++ b/clang/docs/analyzer/user-docs/Annotations.md @@ -8,7 +8,7 @@ analyzer's ability to find bugs. This page gives a practical overview of such annotations. For more technical specifics regarding Clang-specific annotations please see the Clang's list of -[language extensions](https://clang.llvm.org/docs/LanguageExtensions.html). +{doc}`language extensions <../../LanguageExtensions>`. Details of "standard" GCC attributes (that Clang also supports) can be found in the [GCC manual](https://gcc.gnu.org/onlinedocs/gcc/), with the majority of the relevant attributes being in the section on @@ -212,7 +212,7 @@ conventions can cause the analyzer to miss bugs or flag false positives. One can educate the analyzer (and others who read your code) about methods or functions that deviate from the Cocoa and Core Foundation conventions using the attributes described here. However, you should consider using proper naming -conventions or the [objc_method_family](https://clang.llvm.org/docs/LanguageExtensions.html#the-objc-method-family-attribute) +conventions or the [objc_method_family](project:../../AttributeReference.md#objc-method-family) attribute, if applicable. (ns_returns_retained)= @@ -598,7 +598,7 @@ By default, the following summaries are assumed: including the implicit `this` parameter. These summaries can be overriden with the following -[attributes](https://clang.llvm.org/docs/AttributeReference.html#os-returns-not-retained): +{doc}`attributes <../../AttributeReference>`: #### Attribute 'os_returns_retained' >From 2fc4314263e70d65f07d8e13f802f8319bcbf6f9 Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Fri, 11 Sep 2026 21:23:57 +0000 Subject: [PATCH 2/4] [docs] Repair Clang documentation cross-references Restore a stable target for the OSObject retain-behavior attributes and reference it with the Sphinx ref role. Mark links to the generated AST matcher reference as external so MyST preserves their project-relative HTML destinations instead of treating the file as a download. Fixes follow-up issues in #222507. --- clang/docs/ClangTransformerTutorial.md | 2 +- clang/docs/LibASTImporter.md | 2 +- clang/docs/analyzer/user-docs/Annotations.md | 2 +- clang/docs/conf.py | 2 +- clang/include/clang/Basic/AttrDocs.td | 2 ++ 5 files changed, 6 insertions(+), 4 deletions(-) diff --git a/clang/docs/ClangTransformerTutorial.md b/clang/docs/ClangTransformerTutorial.md index 381969ea3a8cf..28a7a428c7bec 100644 --- a/clang/docs/ClangTransformerTutorial.md +++ b/clang/docs/ClangTransformerTutorial.md @@ -367,7 +367,7 @@ introductions on clang's site: - {doc}`Introduction to the Clang AST <IntroductionToTheClangAST>` - {doc}`Matching the Clang AST <LibASTMatchers>` -- [AST Matcher Reference](LibASTMatchersReference.html) +- [AST Matcher Reference](LibASTMatchersReference.html){.external} :::{rubric} Footnotes ::: diff --git a/clang/docs/LibASTImporter.md b/clang/docs/LibASTImporter.md index c0be3c0c28c0d..d9f67f0b090b3 100644 --- a/clang/docs/LibASTImporter.md +++ b/clang/docs/LibASTImporter.md @@ -6,7 +6,7 @@ It imports nodes of an `ASTContext` into another `ASTContext`. In this document, we assume basic knowledge about the Clang AST. See the {doc}`Introduction to the Clang AST <IntroductionToTheClangAST>` if you want to learn more about how the AST is structured. -Knowledge about {doc}`matching the Clang AST <LibASTMatchers>` and the [reference for the matchers](LibASTMatchersReference.html) are also useful. +Knowledge about {doc}`matching the Clang AST <LibASTMatchers>` and the [reference for the matchers](LibASTMatchersReference.html){.external} are also useful. ## Introduction diff --git a/clang/docs/analyzer/user-docs/Annotations.md b/clang/docs/analyzer/user-docs/Annotations.md index 11feb69ea00f8..b1c19c29d309b 100644 --- a/clang/docs/analyzer/user-docs/Annotations.md +++ b/clang/docs/analyzer/user-docs/Annotations.md @@ -598,7 +598,7 @@ By default, the following summaries are assumed: including the implicit `this` parameter. These summaries can be overriden with the following -{doc}`attributes <../../AttributeReference>`: +{ref}`attributes <os-retained-attr-family>`: #### Attribute 'os_returns_retained' diff --git a/clang/docs/conf.py b/clang/docs/conf.py index 122b3f50878a1..82e4385e504bd 100644 --- a/clang/docs/conf.py +++ b/clang/docs/conf.py @@ -19,7 +19,7 @@ globals().update(common_conf(tags, markdown=Markdown.EXCEPT_MAN)) -myst_enable_extensions += ["deflist"] +myst_enable_extensions += ["attrs_inline", "deflist"] # -- General configuration ----------------------------------------------------- diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td index 3b733b820bed5..b5f25e36f7a62 100644 --- a/clang/include/clang/Basic/AttrDocs.td +++ b/clang/include/clang/Basic/AttrDocs.td @@ -1823,6 +1823,8 @@ have the same respective semantics when applied to CoreFoundation objects. These attributes affect code generation when interacting with ARC code, and they are used by the Clang Static Analyzer. +(os-retained-attr-family)= + Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), the same attribute family is present: `__attribute__((os_returns_not_retained))`, >From ac740986c37af7a5bd26d68608509a79736ea9eb Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Tue, 15 Sep 2026 19:01:18 +0000 Subject: [PATCH 3/4] [docs] Prefer portable Clang documentation links Enable the absolute-link checker for Clang and replace nonportable project: links with relative source paths. This preserves MyST link validation while making the links work when browsing sources on GitHub. Also correct the stale RAVFrontendAction suffix and cover links to reST sources and links inside colon-fenced Markdown directive content. --- clang/docs/AllocToken.md | 4 ++-- clang/docs/ClangOffloadBundler.md | 2 +- clang/docs/ControlFlowIntegrityDesign.md | 2 +- clang/docs/IntroductionToTheClangAST.md | 3 +-- clang/docs/LanguageExtensions.md | 8 ++++---- clang/docs/LifetimeSafety.md | 12 ++++++------ clang/docs/SafeBuffers.md | 4 ++-- .../user-docs/SummaryExtraction.md | 2 +- clang/docs/WarningSuppressionMappings.md | 2 +- clang/docs/analyzer/checkers.md | 8 ++++---- clang/docs/analyzer/user-docs/Annotations.md | 2 +- clang/docs/conf.py | 3 +++ llvm/docs/SphinxQuickstartTemplate.md | 3 +-- utils/docs/llvm_sphinx/ext/absolute_links.py | 1 + .../llvm_sphinx/ext/absolute_links_test/markdown.md | 5 +++++ 15 files changed, 34 insertions(+), 27 deletions(-) diff --git a/clang/docs/AllocToken.md b/clang/docs/AllocToken.md index 96aa05c045b24..136f76bfb3111 100644 --- a/clang/docs/AllocToken.md +++ b/clang/docs/AllocToken.md @@ -166,8 +166,8 @@ the allocation call the wrapper returns, which is then instrumented normally. Wrappers that are not inlined still require `-fsanitize-alloc-token-extended`. -[malloc-attribute]: project:AttributeReference.md#malloc -[alloc-size-attribute]: project:AttributeReference.md#alloc-size +[malloc-attribute]: AttributeReference.md#malloc +[alloc-size-attribute]: AttributeReference.md#alloc-size ### Disabling Instrumentation diff --git a/clang/docs/ClangOffloadBundler.md b/clang/docs/ClangOffloadBundler.md index d9d1d263d1e1c..45f9fba0a50aa 100644 --- a/clang/docs/ClangOffloadBundler.md +++ b/clang/docs/ClangOffloadBundler.md @@ -279,7 +279,7 @@ without differentiation based on offload kind. **target-triple** -: The target triple of the code object. See [Target Triple](project:CrossCompilation.md#target-triple). +: The target triple of the code object. See [Target Triple](CrossCompilation.md#target-triple). LLVM target triples can be with or without the optional environment field: diff --git a/clang/docs/ControlFlowIntegrityDesign.md b/clang/docs/ControlFlowIntegrityDesign.md index 4dad111116acb..1b3348928c859 100644 --- a/clang/docs/ControlFlowIntegrityDesign.md +++ b/clang/docs/ControlFlowIntegrityDesign.md @@ -780,5 +780,5 @@ ability to protect against invalid casts between polymorphic types. [globalsplit]: https://github.com/llvm/llvm-project/blob/main/llvm/lib/Transforms/IPO/GlobalSplit.cpp [intel cet]: https://software.intel.com/en-us/blogs/2016/06/09/intel-release-new-technology-specifications-protect-rop-attacks [rfg]: https://xlab.tencent.com/en/2016/11/02/return-flow-guard -[safestack]: project:SafeStack.md +[safestack]: SafeStack.md [type metadata]: https://llvm.org/docs/TypeMetadata.html diff --git a/clang/docs/IntroductionToTheClangAST.md b/clang/docs/IntroductionToTheClangAST.md index 10831c91579b3..b429e0b770f8e 100644 --- a/clang/docs/IntroductionToTheClangAST.md +++ b/clang/docs/IntroductionToTheClangAST.md @@ -108,8 +108,7 @@ and then recursively traverses everything that can be reached from that node - this information has to be encoded for each specific node type. This algorithm is encoded in the [RecursiveASTVisitor](https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html). -See the [RecursiveASTVisitor -tutorial](project:RAVFrontendAction.rst). +See the [RecursiveASTVisitor tutorial](RAVFrontendAction.md). The two most basic nodes in the Clang AST are statements ([Stmt](https://clang.llvm.org/doxygen/classclang_1_1Stmt.html)) and diff --git a/clang/docs/LanguageExtensions.md b/clang/docs/LanguageExtensions.md index 508d0e2fa3003..8a5bbad819170 100644 --- a/clang/docs/LanguageExtensions.md +++ b/clang/docs/LanguageExtensions.md @@ -2582,7 +2582,7 @@ and `-respondsToSelector:` or `+instancesRespondToSelector:` for Objective-C methods. If such a check was missed, the program would compile fine, run fine on newer systems, but crash on older systems. -As of LLVM 5.0, `-Wunguarded-availability` uses the [availability attributes](project:AttributeReference.md#availability) together +As of LLVM 5.0, `-Wunguarded-availability` uses the [availability attributes](AttributeReference.md#availability) together with the new `@available()` keyword to assist with this issue. When a method that's introduced in the OS newer than the target OS is called, a -Wunguarded-availability warning is emitted if that call is not guarded: @@ -2624,7 +2624,7 @@ void my_fun(NSSomeClass* var) { ``` If the caller of `my_fun()` already checks that `my_fun()` is only called -on 10.12, then add an [availability attribute](project:AttributeReference.md#availability) to it, +on 10.12, then add an [availability attribute](AttributeReference.md#availability) to it, which will also suppress the warning and require that calls to my_fun() are checked: @@ -4715,7 +4715,7 @@ The effect of passing some other value to `__builtin_flt_rounds` is implementation-defined. `__builtin_set_flt_rounds` is currently only supported to work on x86, x86_64, powerpc, powerpc64, Arm and AArch64 targets. These builtins read and modify the floating-point environment, which is not always allowed and may -have unexpected behavior. Please see the section on [Accessing the floating point environment](project:UsersManual.md#accessing-the-floating-point-environment) for more information. +have unexpected behavior. Please see the section on [Accessing the floating point environment](UsersManual.md#accessing-the-floating-point-environment) for more information. ### String builtins @@ -6623,7 +6623,7 @@ more information about subobjects to be determined, so the `type & 1 == 1` case will often give imprecise results when used across a function call boundary even when optimization is enabled. -[The pass_object_size and pass_dynamic_object_size attributes](project:AttributeReference.md#pass-object-size-pass-dynamic-object-size) +[The pass_object_size and pass_dynamic_object_size attributes](AttributeReference.md#pass-object-size-pass-dynamic-object-size) can be used to invisibly pass the object size for a pointer parameter alongside the pointer in a function call. This allows more precise object sizes to be determined both when building without optimizations and in the `type & 1 == 1` diff --git a/clang/docs/LifetimeSafety.md b/clang/docs/LifetimeSafety.md index a7a964af7c6f2..d643aa4cbff2a 100644 --- a/clang/docs/LifetimeSafety.md +++ b/clang/docs/LifetimeSafety.md @@ -22,8 +22,8 @@ This is compile-time analysis; there is no run-time overhead. It tracks pointer validity through intra-procedural data-flow analysis. While it does not require lifetime annotations to get started, in their absence, the analysis treats function calls optimistically, assuming no lifetime effects, thereby potentially missing dangling pointer issues. As more functions are annotated -with attributes like [clang::lifetimebound](project:AttributeReference.md#lifetimebound), [gsl::Owner](project:AttributeReference.md#owner), and -[gsl::Pointer](project:AttributeReference.md#pointer), the analysis can see through these lifetime contracts and enforce +with attributes like [clang::lifetimebound](AttributeReference.md#lifetimebound), [gsl::Owner](AttributeReference.md#owner), and +[gsl::Pointer](AttributeReference.md#pointer), the analysis can see through these lifetime contracts and enforce lifetime safety at call sites with higher accuracy. This approach supports gradual adoption in existing codebases. @@ -122,8 +122,8 @@ void test() { Without these annotations, the analysis may not be able to determine whether a type is owning or borrowing, which can affect analysis precision. For more details on these attributes, see the Clang attribute reference for -[gsl::Owner](project:AttributeReference.md#owner) and -[gsl::Pointer](project:AttributeReference.md#pointer). +[gsl::Owner](AttributeReference.md#owner) and +[gsl::Pointer](AttributeReference.md#pointer). :::{note} Types with mixed ownership semantics (owning some data while holding views to @@ -191,7 +191,7 @@ void test() { } ``` -For more details, see [lifetimebound](project:AttributeReference.md#lifetimebound). +For more details, see [lifetimebound](AttributeReference.md#lifetimebound). ### NoEscape @@ -203,7 +203,7 @@ parameter to escape its scope, for example, by returning it or assigning it to a field or global variable. This is useful for parameters passed to callbacks or visitors that are only used during the call and not stored. -For more details, see [noescape](project:AttributeReference.md#noescape). +For more details, see [noescape](AttributeReference.md#noescape). ## Checks Performed diff --git a/clang/docs/SafeBuffers.md b/clang/docs/SafeBuffers.md index 7159581bc18fc..cba5ad188a680 100644 --- a/clang/docs/SafeBuffers.md +++ b/clang/docs/SafeBuffers.md @@ -321,7 +321,7 @@ int get_last_element(int *pointer, size_t size) { } ``` -This behavior is analogous to `#pragma clang diagnostic` ([documentation](project:UsersManual.md#controlling-diagnostics-via-pragmas)) +This behavior is analogous to `#pragma clang diagnostic` ([documentation](UsersManual.md#controlling-diagnostics-via-pragmas)) However, `#pragma clang unsafe_buffer_usage` is specialized and recommended over `#pragma clang diagnostic` for a number of technical and non-technical reasons. Most importantly, `#pragma clang unsafe_buffer_usage` is more @@ -391,7 +391,7 @@ passed into the wrapper is correct.** ### Flag bounds information discontinuities with `[[clang::unsafe_buffer_usage]]` The clang attribute `[[clang::unsafe_buffer_usage]]` -([attribute documentation](project:AttributeReference.md#unsafe-buffer-usage)) +([attribute documentation](AttributeReference.md#unsafe-buffer-usage)) allows the user to annotate various objects, such as functions or member variables, as incompatible with the Safe Buffers programming model. You are encouraged to do that for arbitrary reasons, but typically the main diff --git a/clang/docs/ScalableStaticAnalysis/user-docs/SummaryExtraction.md b/clang/docs/ScalableStaticAnalysis/user-docs/SummaryExtraction.md index e6dd69106e36e..f493994d1554d 100644 --- a/clang/docs/ScalableStaticAnalysis/user-docs/SummaryExtraction.md +++ b/clang/docs/ScalableStaticAnalysis/user-docs/SummaryExtraction.md @@ -32,4 +32,4 @@ or just happens to have an error, then the error is forwarded as a `scalable-sta These errors can be downgraded into warnings using `-Wno-error=scalable-static-analysis-framework`. These errors can be completely suppressed using `-Wno-scalable-static-analysis-framework`. -See the [diagnostic flags](project:../../DiagnosticsReference.md#wscalable-static-analysis-framework) for the full list of diagnostics controlled by `-Wscalable-static-analysis-framework`. +See the [diagnostic flags](../../DiagnosticsReference.md#wscalable-static-analysis-framework) for the full list of diagnostics controlled by `-Wscalable-static-analysis-framework`. diff --git a/clang/docs/WarningSuppressionMappings.md b/clang/docs/WarningSuppressionMappings.md index e493f23e469b4..350c4ca78dffc 100644 --- a/clang/docs/WarningSuppressionMappings.md +++ b/clang/docs/WarningSuppressionMappings.md @@ -26,7 +26,7 @@ flag. Note that this mechanism won't enable any diagnostics on its own. Users should still turn on warnings in their compilations with explicit `-Wfoo` flags. -[Controlling diagnostics pragmas](project:UsersManual.md#controlling-diagnostics-via-pragmas) +[Controlling diagnostics pragmas](UsersManual.md#controlling-diagnostics-via-pragmas) take precedence over suppression mappings. Ensuring code author's explicit intent is always preserved. diff --git a/clang/docs/analyzer/checkers.md b/clang/docs/analyzer/checkers.md index e504e61968a5b..a8c7969e4fa93 100644 --- a/clang/docs/analyzer/checkers.md +++ b/clang/docs/analyzer/checkers.md @@ -197,7 +197,7 @@ void test() { Null pointer dereferences of pointers with address spaces are not always defined as error. Specifically on x86/x86-64 target if the pointer address space is 256 (x86 GS Segment), 257 (x86 FS Segment), or 258 (x86 SS Segment), a null -dereference is not defined as error. See [X86/X86-64 Language Extensions](project:../LanguageExtensions.md#memory-references-to-specified-segments) +dereference is not defined as error. See [X86/X86-64 Language Extensions](../LanguageExtensions.md#memory-references-to-specified-segments) for reference. If the analyzer option `suppress-dereferences-from-any-address-space` is set @@ -808,7 +808,7 @@ This checker does not accept the coding pattern where an enum type is used to store combinations of flag values. Such enums should be annotated with the `__attribute__((flag_enum))` or by the `[[clang::flag_enum]]` attribute to signal this intent. Refer to the -[documentation](project:../AttributeReference.md#flag-enum) +[documentation](../AttributeReference.md#flag-enum) of this Clang attribute. ```cpp @@ -901,7 +901,7 @@ arguments -- even if there is no such call in the codebase. This design rule is dictated by the SEI CERT rule [EXP47-C](https://wiki.sei.cmu.edu/confluence/display/c/EXP47-C.+Do+not+call+va_arg+with+an+argument+of+the+incorrect+type), which describes several issues related to the use of `va_arg()`. (The problem reported by this checker is shown in the second code example; the first, -unrelated code example is covered by the clang diagnostic [-Wvarargs](project:../DiagnosticsReference.md#wvarargs).) +unrelated code example is covered by the clang diagnostic [-Wvarargs](../DiagnosticsReference.md#wvarargs).) ```cpp // This function expects a list of variadic arguments terminated by a NULL pointer. @@ -3357,7 +3357,7 @@ int *direct_return() { The attribute states that the returned value is dangling after the lifetime of the annotated parameter, or of the implicit object argument, has ended. -Refer to the [documentation](project:../AttributeReference.md#lifetimebound) +Refer to the [documentation](../AttributeReference.md#lifetimebound) of this Clang attribute. ```cpp diff --git a/clang/docs/analyzer/user-docs/Annotations.md b/clang/docs/analyzer/user-docs/Annotations.md index b1c19c29d309b..8c9c5f1d08d17 100644 --- a/clang/docs/analyzer/user-docs/Annotations.md +++ b/clang/docs/analyzer/user-docs/Annotations.md @@ -212,7 +212,7 @@ conventions can cause the analyzer to miss bugs or flag false positives. One can educate the analyzer (and others who read your code) about methods or functions that deviate from the Cocoa and Core Foundation conventions using the attributes described here. However, you should consider using proper naming -conventions or the [objc_method_family](project:../../AttributeReference.md#objc-method-family) +conventions or the [objc_method_family](../../AttributeReference.md#objc-method-family) attribute, if applicable. (ns_returns_retained)= diff --git a/clang/docs/conf.py b/clang/docs/conf.py index 82e4385e504bd..1144139c4f459 100644 --- a/clang/docs/conf.py +++ b/clang/docs/conf.py @@ -29,9 +29,12 @@ "sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.graphviz", + "llvm_sphinx.ext.absolute_links", "llvm_sphinx.ext.ghlinks", ] +llvm_sphinx_doc_url_prefixes = ("https://clang.llvm.org/docs/";,) + import sphinx # General information about the project. diff --git a/llvm/docs/SphinxQuickstartTemplate.md b/llvm/docs/SphinxQuickstartTemplate.md index 68fd7c60278cf..a7a69582579e4 100644 --- a/llvm/docs/SphinxQuickstartTemplate.md +++ b/llvm/docs/SphinxQuickstartTemplate.md @@ -109,8 +109,7 @@ GitHub. Likewise, do not link to generated paths such as `CMake.html`. Use a Sphinx `{ref}` role when the target is an explicit label rather than a generated heading. Explicit labels are useful when -an anchor must remain stable after its heading or source file is renamed, or -when a target must be exported to another Sphinx project through an inventory. +an anchor must remain stable after its heading or source file is renamed. Avoid adding explicit labels to ordinary headings when a checked Markdown link is sufficient. diff --git a/utils/docs/llvm_sphinx/ext/absolute_links.py b/utils/docs/llvm_sphinx/ext/absolute_links.py index ab038fd2fee46..79183ad0332ae 100644 --- a/utils/docs/llvm_sphinx/ext/absolute_links.py +++ b/utils/docs/llvm_sphinx/ext/absolute_links.py @@ -244,6 +244,7 @@ def run_tests() -> None: "target.html#target-section", "project:target.md#target-document", "target.html#target-document", + "project:rest.rst", ) for link in expected_nonportable_links: if link not in warnings: diff --git a/utils/docs/llvm_sphinx/ext/absolute_links_test/markdown.md b/utils/docs/llvm_sphinx/ext/absolute_links_test/markdown.md index 783fa89028c6e..559f917542624 100644 --- a/utils/docs/llvm_sphinx/ext/absolute_links_test/markdown.md +++ b/utils/docs/llvm_sphinx/ext/absolute_links_test/markdown.md @@ -15,12 +15,17 @@ These nonportable internal links should warn: [project-target]: project:target.md#target-document [html-target]: target.html#target-document +:::{note} +[A project link in Markdown directive content](project:rest.rst) +::: + These links should not warn: - [another project](https://other.example.test/docs/target.html) - [a nonexistent document](https://example.test/docs/missing.html) - [a non-document page](https://example.test/docs/downloads/package.tar.xz) - [source document](target.md) +- [reStructuredText source document](rest.rst) - [source heading](target.md#target-section) - [same-document heading](#markdown-absolute-link-tests) - [an HTML file that is not a document](static.html) >From c9f3521828bbf7f8fbd7a28740498e0eff548675 Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Sat, 19 Sep 2026 16:49:53 +0000 Subject: [PATCH 4/4] Merge main _______________________________________________ llvm-branch-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-branch-commits
