[llvm-branch-commits] [llvm] [docs] Rewrite LangRef.md as Markdown (PR #201975)

[Justin Lebar via llvm-branch-commits]

jlebar wrote:

I pushed the AI's changes to your branch.  Feel free to revert them or whatever, this just seemed like a good way to share them.  The text of the review is below.

The "one thing worth flagging" at the bottom seems significant.

----------

**Written by Fable**

1. Unsourced semantic changes in the assume-operand-bundle docs (LangRef.md ~3214–3270, ~1613). The conversion, billed as a pure rst→md rewrite, silently imported normative text from a newer upstream revision: a never-reviewed grammar block (with a malformed "<tag>"([ <arguments>] ]) line), "attributes" changed to "operand bundles", and new dereferenceable-bundle semantics ("at the point of the assumption… Only %size > 0 implies dereferenceable") plus a matching forward-reference added to the dereferenceable(<n>) attribute. Fixed by restoring the faithful conversion of the source rst at the merge base in all four spots.
2. Empty ```text fences in the llvm.experimental.vp.strided.load/store examples (~24029, ~24085). Each fence opened and immediately closed, with the example IR orphaned outside as tab-indented text — rendering an empty code box plus a detached block. Fixed by moving the IR inside the fences.

Cleanups — all applied:

3. Leftover RST :: markers in three vector-function-abi-variant prose lines → single :.
4. Escaped seq\_cst (×3) and va\_arg (×2) in prose → `seq_cst`/`va_arg` code spans, matching the file's own convention.
5. The lone 4-space-indented module-flags example in Stack Alignment Metadata → fenced ```llvm block (now gets IR highlighting like its sibling examples).
6. Redundant (vp)= anchor (added with no rst counterpart, zero references in-tree, and shadowed by the MyST auto-anchor) → removed.
7. Four cross-doc links pinned to .rst source paths (OpaquePointers.rst ×2, PCSectionsMetadata.rst, ExtendingLLVM.rst) → {doc}` ` role, which survives if those docs are themselves converted to Markdown later.
8. Five anchor-free .md path links (GarbageCollection.md ×3, PointerAuth.md, AssignmentTracking.md) → {doc}` ` role, consolidating on the mechanism already used ~20 times in the file. Anchor-bearing links were left alone, as those legitimately need the path form.

Skipped: nothing — no findings were refuted or judged false positives.

Verification: sphinx-build over llvm/docs completes with zero LangRef warnings, and I checked the rendered LangRef.html directly: the strided-load/store IR now sits inside its text code box, the :: artifacts and backslash escapes are gone, all nine converted links resolve to the right .html targets, and the restored assume/dereferenceable wording matches the source rst. Net diff: llvm/docs/LangRef.md, +45/−72 lines, uncommitted in the working tree.

One thing worth flagging to the PR author: the imported newer-upstream text in finding 1 suggests the conversion may have been done against a different LLVM revision than the branch point — worth a skim for other sections that drifted the same way, though the review's finders didn't surface any others.

https://github.com/llvm/llvm-project/pull/201975