[clang-tools-extra] dc5d098 - [clang-tools-extra][docs] Convert top-level docs/*.rst to MyST Markdown (#214352)
via cfe-commits
cfe-commits at lists.llvm.org
Fri Aug 7 06:12:53 PDT 2026
Author: Reid Kleckner
Date: 2026-08-07T06:12:43-07:00
New Revision: dc5d098e3d4a77f89d6c4fe999bd27e0ee3eebb8
URL: https://github.com/llvm/llvm-project/commit/dc5d098e3d4a77f89d6c4fe999bd27e0ee3eebb8
DIFF: https://github.com/llvm/llvm-project/commit/dc5d098e3d4a77f89d6c4fe999bd27e0ee3eebb8.diff
LOG: [clang-tools-extra][docs] Convert top-level docs/*.rst to MyST Markdown (#214352)
Tracking issue: #201242
See the [migration guide] for more information.
[migration guide]:
https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
This is a stacked PR based on #214351 , which will be a standalone
commit that
renames *.rst -> *.md before this PR lands for history preservation
purposes.
This PR is structured as two commits:
1. Mechanical, using a fork of rst2myst
2. Agentic cleanup
This structure is used so we can determine why the markdown is the way
it is: either it's rst2myst output, or an agent thought it was a defect,
or it needed manual cleanup to build and pass validation.
I paged through all the generated HTML looking for migration artifacts,
and all of the differences I could find appear to be formatting error
corrections. Please spot check my work and approve if it looks good.
Added:
Modified:
clang-tools-extra/clang-tidy/add_new_check.py
clang-tools-extra/clang-tidy/rename_check.py
clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
clang-tools-extra/docs/ModularizeUsage.md
clang-tools-extra/docs/ReleaseNotes.md
clang-tools-extra/docs/ReleaseNotesTemplate.txt
clang-tools-extra/docs/clang-change-namespace.md
clang-tools-extra/docs/clang-doc.md
clang-tools-extra/docs/clang-include-fixer.md
clang-tools-extra/docs/clang-modernize.md
clang-tools-extra/docs/clang-reorder-fields.md
clang-tools-extra/docs/clang-tidy.md
clang-tools-extra/docs/clangd.md
clang-tools-extra/docs/cpp11-migrate.md
clang-tools-extra/docs/index.md
clang-tools-extra/docs/modularize.md
clang-tools-extra/docs/pp-trace.md
Removed:
################################################################################
diff --git a/clang-tools-extra/clang-tidy/add_new_check.py b/clang-tools-extra/clang-tidy/add_new_check.py
index e26699ead3536..36e3aa6106e55 100755
--- a/clang-tools-extra/clang-tidy/add_new_check.py
+++ b/clang-tools-extra/clang-tidy/add_new_check.py
@@ -261,9 +261,9 @@ def add_release_notes(
with open(filename, "r", encoding="utf8") as f:
lines = f.readlines()
- lineMatcher = re.compile("New checks")
- nextSectionMatcher = re.compile("New check aliases")
- checkMatcher = re.compile("- New :doc:`(.*)")
+ lineMatcher = re.compile(r"#### New checks")
+ nextSectionMatcher = re.compile(r"#### New check aliases")
+ checkMatcher = re.compile(r"- New \{doc\}`(.*)")
print(f"Updating {filename}...")
with open(filename, "w", encoding="utf8", newline="\n") as f:
@@ -286,21 +286,16 @@ def add_release_notes(
f.write(line)
continue
- if line.startswith("^^^^"):
- f.write(line)
- continue
-
if header_found and add_note_here:
- if not line.startswith("^^^^"):
- f.write(
- f"""- New :doc:`{check_name_dashes}
+ f.write(
+ f"""- New {{doc}}`{check_name_dashes}
<clang-tidy/checks/{module}/{check_name}>` check.
{wrapped_desc}
"""
- )
- note_added = True
+ )
+ note_added = True
f.write(line)
diff --git a/clang-tools-extra/clang-tidy/rename_check.py b/clang-tools-extra/clang-tidy/rename_check.py
index 64365a6c811ed..18c998e839994 100755
--- a/clang-tools-extra/clang-tidy/rename_check.py
+++ b/clang-tools-extra/clang-tidy/rename_check.py
@@ -188,8 +188,8 @@ def add_release_notes(
with io.open(filename, "r", encoding="utf8") as f:
lines = f.readlines()
- lineMatcher = re.compile("Renamed checks")
- nextSectionMatcher = re.compile("Improvements to include-fixer")
+ lineMatcher = re.compile(r"#### Renamed checks")
+ nextSectionMatcher = re.compile(r"### Improvements to include-fixer")
checkMatcher = re.compile("- The '(.*)")
print("Updating %s..." % filename)
@@ -211,30 +211,29 @@ def add_release_notes(
if match_next:
add_note_here = True
+ # When inside the Renamed checks section and we reach any
+ # heading, insert before it (handles empty sections).
+ if header_found and line.startswith("#"):
+ add_note_here = True
+
if match:
header_found = True
f.write(line)
continue
- if line.startswith("^^^^"):
- f.write(line)
- continue
-
if header_found and add_note_here:
- if not line.startswith("^^^^"):
- f.write(
- """- The '%s' check was renamed to :doc:`%s
- <clang-tidy/checks/%s/%s>`
-
- """
- % (
- old_check_name,
- new_check_name,
- new_check_name.split("-", 1)[0],
- "-".join(new_check_name.split("-")[1:]),
- )
+ f.write(
+ "- The '%s' check was renamed to {doc}`%s\n"
+ " <clang-tidy/checks/%s/%s>`\n"
+ "\n"
+ % (
+ old_check_name,
+ new_check_name,
+ new_check_name.split("-", 1)[0],
+ "-".join(new_check_name.split("-")[1:]),
)
- note_added = True
+ )
+ note_added = True
f.write(line)
diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
index 6e646e05020bc..ab700e5115ead 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
@@ -42,10 +42,10 @@
Tuple,
)
-# Matches a :doc:`label <path>` or :doc:`label` reference anywhere in text and
+# Matches a {doc}`label <path>` or {doc}`label` reference anywhere in text and
# captures the label. Used to sort bullet items alphabetically in ReleaseNotes
# items by their label.
-DOC_LABEL_RN_RE: Final = re.compile(r":doc:`(?P<label>[^`<]+)\s*(?:<[^>]+>)?`")
+DOC_LABEL_RN_RE: Final = re.compile(r"\{doc\}`(?P<label>[^`<]+)\s*(?:<[^>]+>)?`")
# Matches a single Markdown table row line in list.md that begins with a
# {doc} reference, capturing the label. Used to extract the sort key per row.
@@ -114,11 +114,7 @@ def _scan_bullet_blocks(lines: Sequence[str], start: int, end: int) -> ScannedBl
bstart = i
i += 1
while i < n and not _is_bullet_start(lines[i]):
- if (
- i + 1 < n
- and set(lines[i + 1].rstrip("\n")) == {"^"}
- and lines[i].strip()
- ):
+ if lines[i].startswith("#"):
break
i += 1
block: BulletBlock = list(lines[bstart:i])
@@ -183,22 +179,17 @@ def normalize_list_md(data: str) -> str:
def find_heading(lines: Sequence[str], title: str) -> Optional[int]:
- """Find heading start index for a section underlined with ^ characters.
+ """Find heading start index for a Markdown #### section heading.
- The function looks for a line equal to `title` followed by a line that
- consists solely of ^, which matches the ReleaseNotes style for subsection
- headings used here.
+ The function looks for a line equal to `#### {title}`, matching the
+ ReleaseNotes.md style for subsection headings.
Returns index of the title line, or None if not found.
"""
- for i in range(len(lines) - 1):
- if lines[i].rstrip("\n") == title:
- if (
- (underline := lines[i + 1].rstrip("\n"))
- and set(underline) == {"^"}
- and len(underline) == len(title)
- ):
- return i
+ target = f"#### {title}"
+ for i in range(len(lines)):
+ if lines[i].rstrip("\n") == target:
+ return i
return None
@@ -283,37 +274,29 @@ def _find_section_bounds(
"""Return (h_start, sec_start, sec_end) for section `title`.
- h_start: index of the section title line
- - sec_start: index of the first content line after underline
+ - sec_start: index of the first content line after the heading
- sec_end: index of the first line of the next section title (or end)
"""
if (h_start := find_heading(lines, title)) is None:
return None
- sec_start = h_start + 2
+ sec_start = h_start + 1
# Determine end of section either from next_title or by scanning.
if next_title is not None:
if (h_end := find_heading(lines, next_title)) is None:
- # Scan forward to the next heading-like underline.
+ # Scan forward to the next Markdown heading of any level.
h_end = sec_start
while h_end < len(lines):
- if (
- h_end + 1 < len(lines)
- and lines[h_end].strip()
- and set(lines[h_end + 1].rstrip("\n")) == {"^"}
- ):
+ if lines[h_end].startswith("#"):
break
h_end += 1
sec_end = h_end
else:
- # Scan to end or until a heading underline is found.
+ # Scan to end or until a Markdown heading is found.
h_end = sec_start
while h_end < len(lines):
- if (
- h_end + 1 < len(lines)
- and lines[h_end].strip()
- and set(lines[h_end + 1].rstrip("\n")) == {"^"}
- ):
+ if lines[h_end].startswith("#"):
break
h_end += 1
sec_end = h_end
diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
index 9fa942905fb85..dd79d416ee0a9 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
@@ -45,13 +45,12 @@ def test_normalize_list_md_sorts_rows(self) -> None:
def test_find_heading(self) -> None:
text = textwrap.dedent(
"""\
- - Deprecated the :program:`clang-tidy` ``zircon`` module. All checks have been
- moved to the ``fuchsia`` module instead. The ``zircon`` module will be removed
+ - Deprecated the {program}`clang-tidy` `zircon` module. All checks have been
+ moved to the `fuchsia` module instead. The `zircon` module will be removed
in the 24th release.
- New checks
- ^^^^^^^^^^
- - New :doc:`bugprone-derived-method-shadowing-base-method
+ #### New checks
+ - New {doc}`bugprone-derived-method-shadowing-base-method
<clang-tidy/checks/bugprone/derived-method-shadowing-base-method>` check.
"""
)
@@ -63,23 +62,22 @@ def test_duplicate_detection_and_report(self) -> None:
# Ensure duplicate detection works properly when sorting is incorrect.
text = textwrap.dedent(
"""\
- Changes in existing checks
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #### Changes in existing checks
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - Improved :doc:`bugprone-exception-escape
+ - Improved {doc}`bugprone-exception-escape
<clang-tidy/checks/bugprone/exception-escape>` check's handling of lambdas:
exceptions from captures are now diagnosed, exceptions in the bodies of
lambdas that aren't actually invoked are not.
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
"""
)
@@ -94,19 +92,19 @@ def test_duplicate_detection_and_report(self) -> None:
Please merge these entries into a single bullet point.
- -- Duplicate: - Improved :doc:`bugprone-easily-swappable-parameters
+ -- Duplicate: - Improved {doc}`bugprone-easily-swappable-parameters
- - At line 4:
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - At line 3:
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - At line 14:
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - At line 13:
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
"""
)
@@ -116,15 +114,14 @@ def test_process_release_notes_with_unsorted_content(self) -> None:
# When content is not normalized, the function writes normalized text and returns 0.
rn_text = textwrap.dedent(
"""\
- New checks
- ^^^^^^^^^^
+ #### New checks
- - New :doc:`readability-redundant-parentheses
+ - New {doc}`readability-redundant-parentheses
<clang-tidy/checks/readability/redundant-parentheses>` check.
Detect redundant parentheses.
- - New :doc:`bugprone-derived-method-shadowing-base-method
+ - New {doc}`bugprone-derived-method-shadowing-base-method
<clang-tidy/checks/bugprone/derived-method-shadowing-base-method>` check.
Finds derived class methods that shadow a (non-virtual) base class method.
@@ -147,15 +144,14 @@ def test_process_release_notes_with_unsorted_content(self) -> None:
expected_out = textwrap.dedent(
"""\
- New checks
- ^^^^^^^^^^
+ #### New checks
- - New :doc:`bugprone-derived-method-shadowing-base-method
+ - New {doc}`bugprone-derived-method-shadowing-base-method
<clang-tidy/checks/bugprone/derived-method-shadowing-base-method>` check.
Finds derived class methods that shadow a (non-virtual) base class method.
- - New :doc:`readability-redundant-parentheses
+ - New {doc}`readability-redundant-parentheses
<clang-tidy/checks/readability/redundant-parentheses>` check.
Detect redundant parentheses.
@@ -170,23 +166,22 @@ def test_process_release_notes_prioritizes_sorting_over_duplicates(self) -> None
# Sorting is incorrect and duplicates exist, should report ordering issues first.
rn_text = textwrap.dedent(
"""\
- Changes in existing checks
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #### Changes in existing checks
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - Improved :doc:`bugprone-exception-escape
+ - Improved {doc}`bugprone-exception-escape
<clang-tidy/checks/bugprone/exception-escape>` check's handling of lambdas:
exceptions from captures are now diagnosed, exceptions in the bodies of
lambdas that aren't actually invoked are not.
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
"""
)
@@ -209,20 +204,19 @@ def test_process_release_notes_prioritizes_sorting_over_duplicates(self) -> None
out = f.read()
expected_out = textwrap.dedent(
"""\
- Changes in existing checks
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #### Changes in existing checks
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - Improved :doc:`bugprone-exception-escape
+ - Improved {doc}`bugprone-exception-escape
<clang-tidy/checks/bugprone/exception-escape>` check's handling of lambdas:
exceptions from captures are now diagnosed, exceptions in the bodies of
lambdas that aren't actually invoked are not.
@@ -235,20 +229,19 @@ def test_process_release_notes_with_duplicates_fails(self) -> None:
# Sorting is already correct but duplicates exist, should return 3 and report.
rn_text = textwrap.dedent(
"""\
- Changes in existing checks
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #### Changes in existing checks
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - Improved :doc:`bugprone-exception-escape
+ - Improved {doc}`bugprone-exception-escape
<clang-tidy/checks/bugprone/exception-escape>` check's handling of lambdas:
exceptions from captures are now diagnosed, exceptions in the bodies of
lambdas that aren't actually invoked are not.
@@ -272,19 +265,19 @@ def test_process_release_notes_with_duplicates_fails(self) -> None:
Please merge these entries into a single bullet point.
- -- Duplicate: - Improved :doc:`bugprone-easily-swappable-parameters
+ -- Duplicate: - Improved {doc}`bugprone-easily-swappable-parameters
- - At line 4:
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - At line 3:
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - At line 9:
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - At line 8:
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
"""
)
@@ -297,25 +290,24 @@ def test_process_release_notes_with_duplicates_fails(self) -> None:
def test_release_notes_handles_nested_sub_bullets(self) -> None:
rn_text = textwrap.dedent(
"""\
- Changes in existing checks
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #### Changes in existing checks
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - Improved :doc:`llvm-prefer-isa-or-dyn-cast-in-conditionals
+ - Improved {doc}`llvm-prefer-isa-or-dyn-cast-in-conditionals
<clang-tidy/checks/llvm/prefer-isa-or-dyn-cast-in-conditionals>` check:
- Fix-it handles callees with nested-name-specifier correctly.
- - ``if`` statements with init-statement (``if (auto X = ...; ...)``) are
+ - `if` statements with init-statement (`if (auto X = ...; ...)`) are
handled correctly.
- - ``for`` loops are supported.
+ - `for` loops are supported.
- - Improved :doc:`bugprone-exception-escape
+ - Improved {doc}`bugprone-exception-escape
<clang-tidy/checks/bugprone/exception-escape>` check's handling of lambdas:
exceptions from captures are now diagnosed, exceptions in the bodies of
lambdas that aren't actually invoked are not.
@@ -327,28 +319,27 @@ def test_release_notes_handles_nested_sub_bullets(self) -> None:
expected_out = textwrap.dedent(
"""\
- Changes in existing checks
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #### Changes in existing checks
- - Improved :doc:`bugprone-easily-swappable-parameters
+ - Improved {doc}`bugprone-easily-swappable-parameters
<clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
correcting a spelling mistake on its option
- ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+ `NamePrefixSuffixSilenceDissimilarityTreshold`.
- - Improved :doc:`bugprone-exception-escape
+ - Improved {doc}`bugprone-exception-escape
<clang-tidy/checks/bugprone/exception-escape>` check's handling of lambdas:
exceptions from captures are now diagnosed, exceptions in the bodies of
lambdas that aren't actually invoked are not.
- - Improved :doc:`llvm-prefer-isa-or-dyn-cast-in-conditionals
+ - Improved {doc}`llvm-prefer-isa-or-dyn-cast-in-conditionals
<clang-tidy/checks/llvm/prefer-isa-or-dyn-cast-in-conditionals>` check:
- Fix-it handles callees with nested-name-specifier correctly.
- - ``if`` statements with init-statement (``if (auto X = ...; ...)``) are
+ - `if` statements with init-statement (`if (auto X = ...; ...)`) are
handled correctly.
- - ``for`` loops are supported.
+ - `for` loops are supported.
"""
)
@@ -357,18 +348,17 @@ def test_release_notes_handles_nested_sub_bullets(self) -> None:
def test_release_notes_handles_multiline_doc(self) -> None:
rn_text = textwrap.dedent(
"""\
- Changes in existing checks
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #### Changes in existing checks
- - Renamed :doc:`performance-faster-string-find
+ - Renamed {doc}`performance-faster-string-find
<clang-tidy/checks/performance/faster-string-find>` to
- :doc:`performance-faster-string-operation
+ {doc}`performance-faster-string-operation
<clang-tidy/checks/performance/faster-string-operation>`.
The `performance-faster-string-find` name is kept as an alias.
- - Renamed :doc:`google-explicit-constructor
+ - Renamed {doc}`google-explicit-constructor
<clang-tidy/checks/google/explicit-constructor>`
- to :doc:`misc-explicit-constructor
+ to {doc}`misc-explicit-constructor
<clang-tidy/checks/misc/explicit-constructor>`. The
`google-explicit-constructor`
name is kept as an alias.
@@ -380,19 +370,18 @@ def test_release_notes_handles_multiline_doc(self) -> None:
expected_out = textwrap.dedent(
"""\
- Changes in existing checks
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #### Changes in existing checks
- - Renamed :doc:`google-explicit-constructor
+ - Renamed {doc}`google-explicit-constructor
<clang-tidy/checks/google/explicit-constructor>`
- to :doc:`misc-explicit-constructor
+ to {doc}`misc-explicit-constructor
<clang-tidy/checks/misc/explicit-constructor>`. The
`google-explicit-constructor`
name is kept as an alias.
- - Renamed :doc:`performance-faster-string-find
+ - Renamed {doc}`performance-faster-string-find
<clang-tidy/checks/performance/faster-string-find>` to
- :doc:`performance-faster-string-operation
+ {doc}`performance-faster-string-operation
<clang-tidy/checks/performance/faster-string-operation>`.
The `performance-faster-string-find` name is kept as an alias.
diff --git a/clang-tools-extra/docs/ModularizeUsage.md b/clang-tools-extra/docs/ModularizeUsage.md
index 9f01165653b46..20ca1b0bda84f 100644
--- a/clang-tools-extra/docs/ModularizeUsage.md
+++ b/clang-tools-extra/docs/ModularizeUsage.md
@@ -1,15 +1,13 @@
-================
-Modularize Usage
-================
+# Modularize Usage
-``modularize [<modularize-options>] [<module-map>|<include-files-list>]*
-[<front-end-options>...]``
+`modularize [<modularize-options>] [<module-map>|<include-files-list>]*
+[<front-end-options>...]`
-``<modularize-options>`` is a place-holder for options
+`<modularize-options>` is a place-holder for options
specific to modularize, which are described below in
`Modularize Command Line Options`.
-``<module-map>`` specifies the path of a file name for an
+`<module-map>` specifies the path of a file name for an
existing module map. The module map must be well-formed in
terms of syntax. Modularize will extract the header file names
from the map. Only normal headers are checked, assuming headers
@@ -18,81 +16,82 @@ as a top-level include, assuming they either are included by
other headers which are checked, or they are not suitable for
modules.
-``<include-files-list>`` specifies the path of a file name for a
+`<include-files-list>` specifies the path of a file name for a
file containing the newline-separated list of headers to check
with respect to each other. Lines beginning with '#' and empty
lines are ignored. Header file names followed by a colon and
other space-separated file names will include those extra files
as dependencies. The file names can be relative or full paths,
-but must be on the same line. For example::
+but must be on the same line. For example:
- header1.h
- header2.h
- header3.h: header1.h header2.h
+```
+header1.h
+header2.h
+header3.h: header1.h header2.h
+```
-Note that unless a ``-prefix (header path)`` option is specified,
+Note that unless a `-prefix (header path)` option is specified,
non-absolute file paths in the header list file will be relative
to the header list file directory. Use -prefix to specify a
diff erent
directory.
-``<front-end-options>`` is a place-holder for regular Clang
-front-end arguments, which must follow the <include-files-list>.
+`<front-end-options>` is a place-holder for regular Clang
+front-end arguments, which must follow the `<include-files-list>`.
Note that by default, modularize assumes .h files
contain C++ source, so if you are using a
diff erent language,
-you might need to use a ``-x`` option to tell Clang that the
-header contains another language, i.e.: ``-x c``
+you might need to use a `-x` option to tell Clang that the
+header contains another language, i.e.: `-x c`
Note also that because modularize does not use the clang driver,
you will likely need to pass in additional compiler front-end
arguments to match those passed in by default by the driver.
-Modularize Command Line Options
-===============================
-
-.. option:: -prefix=<header-path>
-
- Prepend the given path to non-absolute file paths in the header list file.
- By default, headers are assumed to be relative to the header list file
- directory. Use ``-prefix`` to specify a
diff erent directory.
-
-.. option:: -module-map-path=<module-map-path>
-
- Generate a module map and output it to the given file. See the description
- in :ref:`module-map-generation`.
-
-.. option:: -problem-files-list=<problem-files-list-file-name>
-
- For use only with module map assistant. Input list of files that
- have problems with respect to modules. These will still be
- included in the generated module map, but will be marked as
- "excluded" headers.
-
-.. option:: -root-module=<root-name>
-
- Put modules generated by the -module-map-path option in an enclosing
- module with the given name. See the description in :ref:`module-map-generation`.
-
-.. option:: -block-check-header-list-only
-
- Limit the #include-inside-extern-or-namespace-block
- check to only those headers explicitly listed in the header list.
- This is a work-around for avoiding error messages for private includes that
- purposefully get included inside blocks.
-
-.. option:: -no-coverage-check
-
- Don't do the coverage check for a module map.
-
-.. option:: -coverage-check-only
-
- Only do the coverage check for a module map.
-
-.. option:: -display-file-lists
-
- Display lists of good files (no compile errors), problem files,
- and a combined list with problem files preceded by a '#'.
- This can be used to quickly determine which files have problems.
- The latter combined list might be useful in starting to modularize
- a set of headers. You can start with a full list of headers,
- use -display-file-lists option, and then use the combined list as
- your intermediate list, uncommenting-out headers as you fix them.
+## Modularize Command Line Options
+
+:::{option} -prefix=<header-path>
+Prepend the given path to non-absolute file paths in the header list file.
+By default, headers are assumed to be relative to the header list file
+directory. Use `-prefix` to specify a
diff erent directory.
+:::
+
+:::{option} -module-map-path=<module-map-path>
+Generate a module map and output it to the given file. See the description
+in {ref}`module-map-generation`.
+:::
+
+:::{option} -problem-files-list=<problem-files-list-file-name>
+For use only with module map assistant. Input list of files that
+have problems with respect to modules. These will still be
+included in the generated module map, but will be marked as
+"excluded" headers.
+:::
+
+:::{option} -root-module=<root-name>
+Put modules generated by the -module-map-path option in an enclosing
+module with the given name. See the description in {ref}`module-map-generation`.
+:::
+
+:::{option} -block-check-header-list-only
+Limit the #include-inside-extern-or-namespace-block
+check to only those headers explicitly listed in the header list.
+This is a work-around for avoiding error messages for private includes that
+purposefully get included inside blocks.
+:::
+
+:::{option} -no-coverage-check
+Don't do the coverage check for a module map.
+:::
+
+:::{option} -coverage-check-only
+Only do the coverage check for a module map.
+:::
+
+:::{option} -display-file-lists
+Display lists of good files (no compile errors), problem files,
+and a combined list with problem files preceded by a '#'.
+This can be used to quickly determine which files have problems.
+The latter combined list might be useful in starting to modularize
+a set of headers. You can start with a full list of headers,
+use -display-file-lists option, and then use the combined list as
+your intermediate list, uncommenting-out headers as you fix them.
+:::
diff --git a/clang-tools-extra/docs/ReleaseNotes.md b/clang-tools-extra/docs/ReleaseNotes.md
index 64f7f7d400550..28da9da42d8ce 100644
--- a/clang-tools-extra/docs/ReleaseNotes.md
+++ b/clang-tools-extra/docs/ReleaseNotes.md
@@ -1,161 +1,144 @@
-.. If you want to modify sections/contents permanently, you should modify both
- ReleaseNotes.rst and ReleaseNotesTemplate.txt.
+---
+myst:
+ enable_extensions:
+ - attrs_block
+ - colon_fence
+ - substitution
+---
-====================================================
-Extra Clang Tools |release| |ReleaseNotesTitle|
-====================================================
+% If you want to modify sections/contents permanently, you should modify both
+% ReleaseNotes.md and ReleaseNotesTemplate.txt.
-.. contents::
- :local:
- :depth: 3
+{#extra-clang-tools-release-releasenotestitle}
+# Extra Clang Tools {{env.config.release}} {{ (('(In-Progress) ' if env.app.tags.has('PreRelease') else '') ~ 'Release Notes') }}
-Written by the `LLVM Team <https://llvm.org/>`_
+```{contents}
+:depth: 3
+:local: true
+```
-.. only:: PreRelease
+Written by the [LLVM Team](https://llvm.org/)
- .. warning::
- These are in-progress notes for the upcoming Extra Clang Tools |version| release.
- Release notes for previous releases can be found on
- `the Download Page <https://releases.llvm.org/download.html>`_.
+::::{only} PreRelease
-Introduction
-============
+:::{warning}
+These are in-progress notes for the upcoming Extra Clang Tools {{env.config.version}} release.
+Release notes for previous releases can be found on
+[the Download Page](https://releases.llvm.org/download.html).
+:::
+::::
+
+## Introduction
This document contains the release notes for the Extra Clang Tools, part of the
-Clang release |release|. Here we describe the status of the Extra Clang Tools in
+Clang release {{env.config.release}}. Here we describe the status of the Extra Clang Tools in
some detail, including major improvements from the previous release and new
-feature work. All LLVM releases may be downloaded from the `LLVM releases web
-site <https://llvm.org/releases/>`_.
+feature work. All LLVM releases may be downloaded from the [LLVM releases web
+site](https://llvm.org/releases/).
For more information about Clang or LLVM, including information about
-the latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or
-the `LLVM Web Site <https://llvm.org>`_.
+the latest release, please see the [Clang Web Site](https://clang.llvm.org) or
+the [LLVM Web Site](https://llvm.org).
Note that if you are reading this file from a Git checkout or the
main Clang web page, this document applies to the *next* release, not
the current one. To see the release notes for a specific release, please
-see the `releases page <https://llvm.org/releases/>`_.
+see the [releases page](https://llvm.org/releases/).
-What's New in Extra Clang Tools |release|?
-==========================================
+{#what-s-new-in-extra-clang-tools-release}
+## What's New in Extra Clang Tools {{env.config.release}}?
Some of the major new features and improvements to Extra Clang Tools are listed
here. Generic improvements to Extra Clang Tools as a whole or to its underlying
infrastructure are described first, followed by tool-specific sections.
-Major New Features
-------------------
+### Major New Features
-Potentially Breaking Changes
-----------------------------
+### Potentially Breaking Changes
-Improvements to clangd
-----------------------
+### Improvements to clangd
-Inlay hints
-^^^^^^^^^^^
+#### Inlay hints
-Diagnostics
-^^^^^^^^^^^
+#### Diagnostics
-Semantic Highlighting
-^^^^^^^^^^^^^^^^^^^^^
+#### Semantic Highlighting
-Compile flags
-^^^^^^^^^^^^^
+#### Compile flags
-Hover
-^^^^^
+#### Hover
-Code completion
-^^^^^^^^^^^^^^^
+#### Code completion
-Code actions
-^^^^^^^^^^^^
+#### Code actions
-Signature help
-^^^^^^^^^^^^^^
+#### Signature help
-Cross-references
-^^^^^^^^^^^^^^^^
+#### Cross-references
-Objective-C
-^^^^^^^^^^^
+#### Objective-C
-Miscellaneous
-^^^^^^^^^^^^^
+#### Miscellaneous
-Improvements to clang-doc
--------------------------
+### Improvements to clang-doc
-Improvements to clang-query
----------------------------
+### Improvements to clang-query
-Improvements to clang-tidy
---------------------------
+### Improvements to clang-tidy
-- Improved :program:`check_clang_tidy.py` by adding support of
- ``-std=cXX-or-earlier`` values, mirroring the existing ``-std=cXX-or-later``.
+- Improved {program}`check_clang_tidy.py` by adding support of
+ `-std=cXX-or-earlier` values, mirroring the existing `-std=cXX-or-later`.
New construct expands to the given standard and every earlier one.
-New checks
-^^^^^^^^^^
+#### New checks
-- New :doc:`performance-expensive-value-or
+- New {doc}`performance-expensive-value-or
<clang-tidy/checks/performance/expensive-value-or>` check.
- Finds calls to ``value_or`` (and alternative spellings ``valueOr``,
- ``ValueOr``) on optional types where the return type is expensive to copy.
+ Finds calls to `value_or` (and alternative spellings `valueOr`,
+ `ValueOr`) on optional types where the return type is expensive to copy.
-New check aliases
-^^^^^^^^^^^^^^^^^
+#### New check aliases
-Changes in existing checks
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Changes in existing checks
-- Improved :doc:`cppcoreguidelines-pro-type-member-init
+- Improved {doc}`cppcoreguidelines-pro-type-member-init
<clang-tidy/checks/cppcoreguidelines/pro-type-member-init>` check by treating
- ``std::array`` the same as built-in arrays when `IgnoreArrays` option is enabled.
+ `std::array` the same as built-in arrays when `IgnoreArrays` option is enabled.
-- Improved :doc:`misc-redundant-expression
+- Improved {doc}`misc-redundant-expression
<clang-tidy/checks/misc/redundant-expression>` by fixing false positives in
nested expressions involving
diff erent macros or a mix of macro and
non-macro operands.
-- Improved :doc:`modernize-return-braced-init-list
+- Improved {doc}`modernize-return-braced-init-list
<clang-tidy/checks/modernize/return-braced-init-list>` check to no longer
rewrite the return value when the constructed type has a
- ``std::initializer_list`` constructor, as the braced form could select a
+ `std::initializer_list` constructor, as the braced form could select a
diff erent constructor.
-- Improved :doc:`readability-named-parameter
+- Improved {doc}`readability-named-parameter
<clang-tidy/checks/readability/named-parameter>` check by ignoring
- standard tag types (e.g. ``std::in_place_t``, ``std::allocator_arg_t``,
- ``std::nothrow_t``, iterator tags, lock tags, etc.) that are used
- exclusively for overload resolution. Added the :option:`IgnoredTypes`
+ standard tag types (e.g. `std::in_place_t`, `std::allocator_arg_t`,
+ `std::nothrow_t`, iterator tags, lock tags, etc.) that are used
+ exclusively for overload resolution. Added the {option}`IgnoredTypes`
option to allow customizing the set of ignored types.
-- Improved :doc:`readability-use-std-min-max
+- Improved {doc}`readability-use-std-min-max
<clang-tidy/checks/readability/use-std-min-max>` check by fixing spurious
- trailing semicolons and lost comments when the ``if`` body has no braces.
+ trailing semicolons and lost comments when the `if` body has no braces.
+
+#### Removed checks
-Removed checks
-^^^^^^^^^^^^^^
+#### Miscellaneous
-Miscellaneous
-^^^^^^^^^^^^^
+### Improvements to include-fixer
-Improvements to include-fixer
------------------------------
+### Improvements to clang-include-fixer
-Improvements to clang-include-fixer
------------------------------------
+### Improvements to modularize
-Improvements to modularize
---------------------------
+### Improvements to pp-trace
-Improvements to pp-trace
-------------------------
+### Clang-tidy Visual Studio plugin
-Clang-tidy Visual Studio plugin
--------------------------------
diff --git a/clang-tools-extra/docs/ReleaseNotesTemplate.txt b/clang-tools-extra/docs/ReleaseNotesTemplate.txt
index 69c3bcf67b8db..8874e1d393c6a 100644
--- a/clang-tools-extra/docs/ReleaseNotesTemplate.txt
+++ b/clang-tools-extra/docs/ReleaseNotesTemplate.txt
@@ -1,125 +1,107 @@
-.. If you want to modify sections/contents permanently, you should modify both
- ReleaseNotes.rst and ReleaseNotesTemplate.txt.
+---
+myst:
+ enable_extensions:
+ - attrs_block
+ - colon_fence
+ - substitution
+---
-====================================================
-Extra Clang Tools |release| |ReleaseNotesTitle|
-====================================================
+% If you want to modify sections/contents permanently, you should modify both
+% ReleaseNotes.md and ReleaseNotesTemplate.txt.
-.. contents::
- :local:
- :depth: 3
+{#extra-clang-tools-release-releasenotestitle}
+# Extra Clang Tools {{env.config.release}} {{ (('(In-Progress) ' if env.app.tags.has('PreRelease') else '') ~ 'Release Notes') }}
-Written by the `LLVM Team <https://llvm.org/>`_
+```{contents}
+:depth: 3
+:local: true
+```
-.. only:: PreRelease
+Written by the [LLVM Team](https://llvm.org/)
- .. warning::
- These are in-progress notes for the upcoming Extra Clang Tools |version| release.
- Release notes for previous releases can be found on
- `the Download Page <https://releases.llvm.org/download.html>`_.
+::::{only} PreRelease
-Introduction
-============
+:::{warning}
+These are in-progress notes for the upcoming Extra Clang Tools {{env.config.version}} release.
+Release notes for previous releases can be found on
+[the Download Page](https://releases.llvm.org/download.html).
+:::
+::::
+
+## Introduction
This document contains the release notes for the Extra Clang Tools, part of the
-Clang release |release|. Here we describe the status of the Extra Clang Tools in
+Clang release {{env.config.release}}. Here we describe the status of the Extra Clang Tools in
some detail, including major improvements from the previous release and new
-feature work. All LLVM releases may be downloaded from the `LLVM releases web
-site <https://llvm.org/releases/>`_.
+feature work. All LLVM releases may be downloaded from the [LLVM releases web
+site](https://llvm.org/releases/).
For more information about Clang or LLVM, including information about
-the latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or
-the `LLVM Web Site <https://llvm.org>`_.
+the latest release, please see the [Clang Web Site](https://clang.llvm.org) or
+the [LLVM Web Site](https://llvm.org).
Note that if you are reading this file from a Git checkout or the
main Clang web page, this document applies to the *next* release, not
the current one. To see the release notes for a specific release, please
-see the `releases page <https://llvm.org/releases/>`_.
+see the [releases page](https://llvm.org/releases/).
-What's New in Extra Clang Tools |release|?
-==========================================
+{#what-s-new-in-extra-clang-tools-release}
+## What's New in Extra Clang Tools {{env.config.release}}?
Some of the major new features and improvements to Extra Clang Tools are listed
here. Generic improvements to Extra Clang Tools as a whole or to its underlying
infrastructure are described first, followed by tool-specific sections.
-Major New Features
-------------------
+### Major New Features
-Potentially Breaking Changes
-----------------------------
+### Potentially Breaking Changes
-Improvements to clangd
-----------------------
+### Improvements to clangd
-Inlay hints
-^^^^^^^^^^^
+#### Inlay hints
-Diagnostics
-^^^^^^^^^^^
+#### Diagnostics
-Semantic Highlighting
-^^^^^^^^^^^^^^^^^^^^^
+#### Semantic Highlighting
-Compile flags
-^^^^^^^^^^^^^
+#### Compile flags
-Hover
-^^^^^
+#### Hover
-Code completion
-^^^^^^^^^^^^^^^
+#### Code completion
-Code actions
-^^^^^^^^^^^^
+#### Code actions
-Signature help
-^^^^^^^^^^^^^^
+#### Signature help
-Cross-references
-^^^^^^^^^^^^^^^^
+#### Cross-references
-Objective-C
-^^^^^^^^^^^
+#### Objective-C
-Miscellaneous
-^^^^^^^^^^^^^
+#### Miscellaneous
-Improvements to clang-doc
--------------------------
+### Improvements to clang-doc
-Improvements to clang-query
----------------------------
+### Improvements to clang-query
-Improvements to clang-tidy
---------------------------
+### Improvements to clang-tidy
-New checks
-^^^^^^^^^^
+#### New checks
-New check aliases
-^^^^^^^^^^^^^^^^^
+#### New check aliases
-Changes in existing checks
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Changes in existing checks
-Removed checks
-^^^^^^^^^^^^^^
+#### Removed checks
-Miscellaneous
-^^^^^^^^^^^^^
+#### Miscellaneous
-Improvements to include-fixer
------------------------------
+### Improvements to include-fixer
-Improvements to clang-include-fixer
------------------------------------
+### Improvements to clang-include-fixer
-Improvements to modularize
---------------------------
+### Improvements to modularize
-Improvements to pp-trace
-------------------------
+### Improvements to pp-trace
-Clang-tidy Visual Studio plugin
--------------------------------
+### Clang-tidy Visual Studio plugin
diff --git a/clang-tools-extra/docs/clang-change-namespace.md b/clang-tools-extra/docs/clang-change-namespace.md
index 1eab83f5069b6..b44c1a359f8ac 100644
--- a/clang-tools-extra/docs/clang-change-namespace.md
+++ b/clang-tools-extra/docs/clang-change-namespace.md
@@ -1,13 +1,13 @@
-======================
-Clang-Change-Namespace
-======================
+# Clang-Change-Namespace
-.. contents::
+```{contents}
+```
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
+```
-:program:`clang-change-namespace` can be used to change the surrounding
+{program}`clang-change-namespace` can be used to change the surrounding
namespaces of class/function definitions.
Classes/functions in the moved namespace will have new namespaces while
@@ -21,170 +21,164 @@ classes, only classes that are declared/defined in the given namespace in
specified files will be moved: forward declarations will remain in the old
namespace. The will be demonstrated in the next example.
-Example usage
--------------
+## Example usage
For example, consider this `test.cc` example here with the forward declared
class `FWD` and the defined class `A`, both in the namespace `a`.
-.. code-block:: c++
-
- namespace a {
- class FWD;
- class A {
- FWD *fwd;
- };
- } // namespace a
+```c++
+namespace a {
+class FWD;
+class A {
+ FWD *fwd;
+};
+} // namespace a
+```
And now let's change the namespace `a` to `x`.
-.. code-block:: console
-
- clang-change-namespace \
- --old_namespace "a" \
- --new_namespace "x" \
- --file_pattern "test.cc" \
- --i \
- test.cc
+```console
+clang-change-namespace \
+ --old_namespace "a" \
+ --new_namespace "x" \
+ --file_pattern "test.cc" \
+ --i \
+ test.cc
+```
Note that in the code below there's still the forward decalred class `FWD` that
stayed in the namespace `a`. It wasn't moved to the new namespace because it
wasn't defined/declared here in `a` but only forward declared.
-.. code-block:: c++
-
- namespace a {
- class FWD;
- } // namespace a
- namespace x {
-
- class A {
- a::FWD *fwd;
- };
- } // namespace x
+```c++
+namespace a {
+class FWD;
+} // namespace a
+namespace x {
+class A {
+ a::FWD *fwd;
+};
+} // namespace x
+```
-Another example
----------------
+## Another example
Consider this `test.cc` file:
-.. code-block:: c++
-
- namespace na {
- class X {};
- namespace nb {
- class Y {
- X x;
- };
- } // namespace nb
- } // namespace na
+```c++
+namespace na {
+class X {};
+namespace nb {
+class Y {
+ X x;
+};
+} // namespace nb
+} // namespace na
+```
To move the definition of class `Y` from namespace `na::nb` to `x::y`, run:
-.. code-block:: console
-
- clang-change-namespace \
- --old_namespace "na::nb" \
- --new_namespace "x::y" \
- --file_pattern "test.cc" \
- --i \
- test.cc
+```console
+clang-change-namespace \
+ --old_namespace "na::nb" \
+ --new_namespace "x::y" \
+ --file_pattern "test.cc" \
+ --i \
+ test.cc
+```
This will overwrite `test.cc` to look like this:
-.. code-block:: c++
+```c++
+namespace na {
+class X {};
- namespace na {
- class X {};
-
- } // namespace na
- namespace x {
- namespace y {
- class Y {
- na::X x;
- };
- } // namespace y
- } // namespace x
+} // namespace na
+namespace x {
+namespace y {
+class Y {
+ na::X x;
+};
+} // namespace y
+} // namespace x
+```
Note, that we've successfully moved the class `Y` from namespace `na::nb` to
namespace `x::y`.
-Caveats
-=======
+### Caveats
-Content already exists in new namespace
----------------------------------------
+## Content already exists in new namespace
Consider this `test.cc` example that defines two `class A` one inside the
namespace `a` and one in namespace `b`:
-.. code-block:: c++
-
- namespace a {
- class A {
- int classAFromWithinNamespace_a;
- };
- } // namespace a
+```c++
+namespace a {
+class A {
+ int classAFromWithinNamespace_a;
+};
+} // namespace a
- namespace b {
- class A {
- int classAFromWithinNamespace_b;
- };
- } //namespace b
+namespace b {
+class A {
+ int classAFromWithinNamespace_b;
+};
+} //namespace b
+```
Let's move everything from namespace `a` to namespace `b`:
-.. code-block:: console
-
- clang-change-namespace \
- --old_namespace "a" \
- --new_namespace "b" \
- --file_pattern test.cc \
- test.cc
+```console
+clang-change-namespace \
+ --old_namespace "a" \
+ --new_namespace "b" \
+ --file_pattern test.cc \
+ test.cc
+```
As expected we now have to definitions of `class A` inside the namespace `b`:
-.. code-block:: c++
-
- namespace b {
- class A {
- int classAFromWithinNamespace_a;
- };
- } // namespace b
+```c++
+namespace b {
+class A {
+ int classAFromWithinNamespace_a;
+};
+} // namespace b
- namespace b {
- class A {
- int classAFromWithinNamespace_b;
- };
- } //namespace b
+namespace b {
+class A {
+ int classAFromWithinNamespace_b;
+};
+} //namespace b
+```
The re-factoring looks correct but the code will not compile due to the name
duplication. It is not up to the tool to ensure compilability in that sense.
But one has to be aware of that.
-Inline namespace doesn't work
------------------------------
+## Inline namespace doesn't work
Consider this usage of two versions of implementations for a `greet` function:
-.. code-block:: c++
+```c++
+#include <cstdio>
- #include <cstdio>
+namespace Greeter {
+inline namespace Version1 {
+ const char* greet() { return "Hello from version 1!"; }
+} // namespace Version1
+namespace Version2 {
+ const char* greet() { return "Hello from version 2!"; }
+} // namespace Version2
+} // namespace Greeter
- namespace Greeter {
- inline namespace Version1 {
- const char* greet() { return "Hello from version 1!"; }
- } // namespace Version1
- namespace Version2 {
- const char* greet() { return "Hello from version 2!"; }
- } // namespace Version2
- } // namespace Greeter
-
- int main(int argc, char* argv[]) {
- printf("%s\n", Greeter::greet());
- return 0;
- }
+int main(int argc, char* argv[]) {
+ printf("%s\n", Greeter::greet());
+ return 0;
+}
+```
Note, that currently `Greeter::greet()` will result in a call to
`Greeter::Version1::greet()` because that's the inlined namespace.
@@ -193,122 +187,119 @@ Let's say you want to move one and make `Version2` the default now and remove
the `inline` from the `Version1`. First let's try to turn `namespace Version2`
into `inline namespace Version2`:
-.. code-block:: console
-
- clang-change-namespace \
- --old_namespace "Greeter::Version2" \
- --new_namespace "inline Version2" \
- --file_pattern main.cc main.cc
+```console
+clang-change-namespace \
+ --old_namespace "Greeter::Version2" \
+ --new_namespace "inline Version2" \
+ --file_pattern main.cc main.cc
+```
But this will put the `inline` keyword in the wrong place resulting in:
-.. code-block:: c++
-
- #include <cstdio>
+```c++
+#include <cstdio>
- namespace Greeter {
- inline namespace Version1 {
- const char* greet() { return "Hello from version 1!"; }
- } // namespace Version1
+namespace Greeter {
+inline namespace Version1 {
+ const char* greet() { return "Hello from version 1!"; }
+} // namespace Version1
- } // namespace Greeter
- namespace inline Greeter {
- namespace Version2 {
- const char *greet() { return "Hello from version 2!"; }
- } // namespace Version2
- } // namespace inline Greeter
+} // namespace Greeter
+namespace inline Greeter {
+namespace Version2 {
+const char *greet() { return "Hello from version 2!"; }
+} // namespace Version2
+} // namespace inline Greeter
- int main(int argc, char* argv[]) {
- printf("%s\n", Greeter::greet());
- return 0;
- }
+int main(int argc, char* argv[]) {
+ printf("%s\n", Greeter::greet());
+ return 0;
+}
+```
-One cannot use `:program:`clang-change-namespace` to inline a namespace.
+One cannot use {program}`clang-change-namespace` to inline a namespace.
-Symbol references not updated
------------------------------
+## Symbol references not updated
Consider this `test.cc` file:
-.. code-block:: c++
+```c++
+namespace old {
+struct foo {};
+} // namespace old
- namespace old {
- struct foo {};
- } // namespace old
-
- namespace b {
- old::foo g_foo;
- } // namespace b
+namespace b {
+old::foo g_foo;
+} // namespace b
+```
Notice that namespace `b` defines a global variable of type `old::foo`. If we
now change the name of the `old` namespace to `modern`, the reference will not
be updated:
-.. code-block:: console
-
- clang-change-namespace \
- --old_namespace "old" \
- --new_namespace "modern" \
- --file_pattern test.cc \
- test.cc
+```console
+clang-change-namespace \
+ --old_namespace "old" \
+ --new_namespace "modern" \
+ --file_pattern test.cc \
+ test.cc
+```
-.. code-block:: c++
+```c++
+namespace modern {
+struct foo {};
+} // namespace modern
- namespace modern {
- struct foo {};
- } // namespace modern
-
- namespace b {
- old::foo g_foo;
- } // namespace b
+namespace b {
+old::foo g_foo;
+} // namespace b
+```
`g_foo` is still of the no longer existing type `old::foo` while instead it
should use `modern::foo`.
Only symbol references in the moved namespace are updated, not outside of it.
+### {program}`clang-change-namespace` Command Line Options
-:program:`clang-change-namespace` Command Line Options
-======================================================
-
-.. option:: --allowed_file=<string>
-
- A file containing regexes of symbol names that are not expected to be updated
- when changing namespaces around them.
-
-.. option:: --dump_result
-
- Dump new file contents in YAML, if specified.
-
-.. option:: --extra-arg=<string>
-
- Additional argument to append to the compiler command line
-
-.. option:: --extra-arg-before=<string>
-
- Additional argument to prepend to the compiler command line
-
-.. option:: --file_pattern=<string>
-
- Only rename namespaces in files that match the given regular expression
- pattern.
-
-.. option:: -i
+:::{option} --allowed_file=<string>
+A file containing regexes of symbol names that are not expected to be updated
+when changing namespaces around them.
+:::
- Inplace edit <file>s, if specified.
+:::{option} --dump_result
+Dump new file contents in YAML, if specified.
+:::
-.. option:: --new_namespace=<string>
+:::{option} --extra-arg=<string>
+Additional argument to append to the compiler command line
+:::
- New namespace. Use `""` when you target the global namespace.
+:::{option} --extra-arg-before=<string>
+Additional argument to prepend to the compiler command line
+:::
-.. option:: --old_namespace=<string>
+:::{option} --file_pattern=<string>
+Only rename namespaces in files that match the given regular expression
+pattern.
+:::
- Old namespace.
+:::{option} -i
+Inplace edit `<file>`s, if specified.
+:::
-.. option:: -p <string>
+:::{option} --new_namespace=<string>
+New namespace. Use `""` when you target the global namespace.
+:::
- Build path
+:::{option} --old_namespace=<string>
+Old namespace.
+:::
-.. option:: --style=<string>
+:::{option} -p <string>
+Build path
+:::
- The style name used for reformatting.
+:::{option} --style=<string>
+The style name used for reformatting.
+:::
diff --git a/clang-tools-extra/docs/clang-doc.md b/clang-tools-extra/docs/clang-doc.md
index d65b986c9016d..11aa4ddaf943d 100644
--- a/clang-tools-extra/docs/clang-doc.md
+++ b/clang-tools-extra/docs/clang-doc.md
@@ -1,122 +1,116 @@
-===================
-Clang-Doc
-===================
+# Clang-Doc
-.. contents::
+```{contents}
+```
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
+```
-:program:`clang-doc` is a tool for generating C and C++ documentation from
+{program}`clang-doc` is a tool for generating C and C++ documentation from
source code and comments.
The tool is in a very early development stage, so you might encounter bugs and
crashes. Submitting reports with information about how to reproduce the issue
-to `the LLVM bug tracker <https://github.com/llvm/llvm-project/issues/>`_ will definitely help the
+to [the LLVM bug tracker](https://github.com/llvm/llvm-project/issues/) will definitely help the
project. If you have any ideas or suggestions, please to put a feature request
there.
-Use
-===
+## Use
-:program:`clang-doc` is a `LibTooling
-<https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and so requires a
+{program}`clang-doc` is a [LibTooling](https://clang.llvm.org/docs/LibTooling.html)-based tool, and so requires a
compile command database for your project (for an example of how to do this
-see `How To Setup Tooling For LLVM
-<https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_).
+see [How To Setup Tooling For LLVM](https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html)).
The tool will process a list of files by default:
-.. code-block:: console
-
- $ clang-doc File1.cpp File2.cpp ... FileN.cpp
+```console
+$ clang-doc File1.cpp File2.cpp ... FileN.cpp
+```
The tool can be also used with a compile commands database:
-.. code-block:: console
-
- $ clang-doc --executor=all-TUs compile_commands.json
-
-To select only a subset of files from the database, use the ``--filter`` flag:
+```console
+$ clang-doc --executor=all-TUs compile_commands.json
+```
-.. code-block:: console
+To select only a subset of files from the database, use the `--filter` flag:
- $ clang-doc --executor=all-TUs --filter=File[0-9]+.cpp compile_commands.json
+```console
+$ clang-doc --executor=all-TUs --filter=File[0-9]+.cpp compile_commands.json
+```
-Output
-======
+## Output
-:program:`clang-doc` produces a directory of documentation. One file is produced
+{program}`clang-doc` produces a directory of documentation. One file is produced
for each namespace and record in the project source code, containing all
documentation (including contained functions, methods, and enums) for that item.
-The top-level directory is configurable through the ``output`` flag:
-
-.. code-block:: console
+The top-level directory is configurable through the `output` flag:
- $ clang-doc --output=output/directory/ compile_commands.json
+```console
+$ clang-doc --output=output/directory/ compile_commands.json
+```
-Configuration
-=============
+## Configuration
-Configuration for :program:`clang-doc` is currently limited to command-line options.
+Configuration for {program}`clang-doc` is currently limited to command-line options.
In the future, it may develop the ability to use a configuration file, but no such
efforts are currently in progress.
-Options
--------
-
-:program:`clang-doc` offers the following options:
-
-.. code-block:: console
+### Options
- $ clang-doc --help
- OVERVIEW: Generates documentation from source code and comments.
+{program}`clang-doc` offers the following options:
- Example usage for files without flags (default):
+```console
+$ clang-doc --help
+OVERVIEW: Generates documentation from source code and comments.
- $ clang-doc File1.cpp File2.cpp ... FileN.cpp
+Example usage for files without flags (default):
- Example usage for a project using a compile commands database:
-
- $ clang-doc --executor=all-TUs compile_commands.json
-
- USAGE: clang-doc [options] <source0> [... <sourceN>]
-
- OPTIONS:
-
- Generic Options:
-
- -help - Display available options (-help-hidden for more)
- -help-list - Display list of available options (-help-list-hidden for more)
- -version - Display the version of this program
+ $ clang-doc File1.cpp File2.cpp ... FileN.cpp
- clang-doc options:
+Example usage for a project using a compile commands database:
- --doxygen - Use only doxygen-style comments to generate docs.
- --extra-arg=<string> - Additional argument to append to the compiler command line
- Can be used several times.
- --extra-arg-before=<string> - Additional argument to prepend to the compiler command line
- Can be used several times.
- --format=<value> - Format for outputted docs.
- =yaml - Documentation in YAML format.
- =md - Documentation in MD format.
- =html - Documentation in HTML format.
- --ignore-map-errors - Continue if files are not mapped correctly.
- --output=<string> - Directory for outputting generated files.
- -p <string> - Build path
- --project-name=<string> - Name of project.
- --public - Document only public declarations.
- --repository=<string> -
- URL of repository that hosts code.
- Used for links to definition locations.
- --source-root=<string> -
- Directory where processed files are stored.
- Links to definition locations will only be
- generated if the file is in this dir.
- --stylesheets=<string> - CSS stylesheets to extend the default styles.
+ $ clang-doc --executor=all-TUs compile_commands.json
-The following flags should only be used if ``format`` is set to ``html``:
-- ``repository``
-- ``source-root``
-- ``stylesheets``
+USAGE: clang-doc [options] <source0> [... <sourceN>]
+
+OPTIONS:
+
+Generic Options:
+
+ -help - Display available options (-help-hidden for more)
+ -help-list - Display list of available options (-help-list-hidden for more)
+ -version - Display the version of this program
+
+clang-doc options:
+
+ --doxygen - Use only doxygen-style comments to generate docs.
+ --extra-arg=<string> - Additional argument to append to the compiler command line
+ Can be used several times.
+ --extra-arg-before=<string> - Additional argument to prepend to the compiler command line
+ Can be used several times.
+ --format=<value> - Format for outputted docs.
+ =yaml - Documentation in YAML format.
+ =md - Documentation in MD format.
+ =html - Documentation in HTML format.
+ --ignore-map-errors - Continue if files are not mapped correctly.
+ --output=<string> - Directory for outputting generated files.
+ -p <string> - Build path
+ --project-name=<string> - Name of project.
+ --public - Document only public declarations.
+ --repository=<string> -
+ URL of repository that hosts code.
+ Used for links to definition locations.
+ --source-root=<string> -
+ Directory where processed files are stored.
+ Links to definition locations will only be
+ generated if the file is in this dir.
+ --stylesheets=<string> - CSS stylesheets to extend the default styles.
+```
+
+The following flags should only be used if `format` is set to `html`:
+- `repository`
+- `source-root`
+- `stylesheets`
diff --git a/clang-tools-extra/docs/clang-include-fixer.md b/clang-tools-extra/docs/clang-include-fixer.md
index 7d1fd9ed70e77..6be1251457310 100644
--- a/clang-tools-extra/docs/clang-include-fixer.md
+++ b/clang-tools-extra/docs/clang-include-fixer.md
@@ -1,145 +1,138 @@
-===================
-Clang-Include-Fixer
-===================
+# Clang-Include-Fixer
-.. contents::
+```{contents}
+```
One of the major nuisances of C++ compared to other languages is the manual
-management of ``#include`` directives in any file.
-:program:`clang-include-fixer` addresses one aspect of this problem by providing
-an automated way of adding ``#include`` directives for missing symbols in one
+management of `#include` directives in any file.
+{program}`clang-include-fixer` addresses one aspect of this problem by providing
+an automated way of adding `#include` directives for missing symbols in one
translation unit.
-While inserting missing ``#include``, :program:`clang-include-fixer` adds
+While inserting missing `#include`, {program}`clang-include-fixer` adds
missing namespace qualifiers to all instances of an unidentified symbol if
the symbol is missing some prefix namespace qualifiers.
-Setup
-=====
+## Setup
-To use :program:`clang-include-fixer` two databases are required. Both can be
+To use {program}`clang-include-fixer` two databases are required. Both can be
generated with existing tools.
- Compilation database. Contains the compiler commands for any given file in a
- project and can be generated by CMake, see `How To Setup Tooling For LLVM`_.
+ project and can be generated by CMake, see [How To Setup Tooling For LLVM][how to setup tooling for llvm].
- Symbol index. Contains all symbol information in a project to match a given
identifier to a header file.
-Ideally both databases (``compile_commands.json`` and
-``find_all_symbols_db.yaml``) are linked into the root of the source tree they
-correspond to. Then the :program:`clang-include-fixer` can automatically pick
+Ideally both databases (`compile_commands.json` and
+`find_all_symbols_db.yaml`) are linked into the root of the source tree they
+correspond to. Then the {program}`clang-include-fixer` can automatically pick
them up if called with a source file from that tree. Note that by default
-``compile_commands.json`` as generated by CMake does not include header files,
+`compile_commands.json` as generated by CMake does not include header files,
so only implementation files can be handled by tools.
-.. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
+### Creating a Symbol Index From a Compilation Database
-Creating a Symbol Index From a Compilation Database
----------------------------------------------------
-
-The include fixer contains :program:`find-all-symbols`, a tool to create a
+The include fixer contains {program}`find-all-symbols`, a tool to create a
symbol database in YAML format from a compilation database by parsing all
source files listed in it. The following list of commands shows how to set up a
database for LLVM, any project built by CMake should follow similar steps.
-.. code-block:: console
-
- $ cd path/to/llvm-build
- $ ninja find-all-symbols // build find-all-symbols tool.
- $ ninja clang-include-fixer // build clang-include-fixer tool.
- $ ls compile_commands.json # Make sure compile_commands.json exists.
- compile_commands.json
- $ path/to/llvm/source/clang-tools-extra/clang-include-fixer/find-all-symbols/tool/run-find-all-symbols.py
- ... wait as clang indexes the code base ...
- $ ln -s $PWD/find_all_symbols_db.yaml path/to/llvm/source/ # Link database into the source tree.
- $ ln -s $PWD/compile_commands.json path/to/llvm/source/ # Also link compilation database if it's not there already.
- $ cd path/to/llvm/source
- $ /path/to/clang-include-fixer -db=yaml path/to/file/with/missing/include.cpp
- Added #include "foo.h"
-
-Integrate with Vim
-------------------
-To run `clang-include-fixer` on a potentially unsaved buffer in Vim. Add the
-following key binding to your ``.vimrc``:
+```console
+$ cd path/to/llvm-build
+$ ninja find-all-symbols // build find-all-symbols tool.
+$ ninja clang-include-fixer // build clang-include-fixer tool.
+$ ls compile_commands.json # Make sure compile_commands.json exists.
+ compile_commands.json
+$ path/to/llvm/source/clang-tools-extra/clang-include-fixer/find-all-symbols/tool/run-find-all-symbols.py
+ ... wait as clang indexes the code base ...
+$ ln -s $PWD/find_all_symbols_db.yaml path/to/llvm/source/ # Link database into the source tree.
+$ ln -s $PWD/compile_commands.json path/to/llvm/source/ # Also link compilation database if it's not there already.
+$ cd path/to/llvm/source
+$ /path/to/clang-include-fixer -db=yaml path/to/file/with/missing/include.cpp
+ Added #include "foo.h"
+```
+
+### Integrate with Vim
-.. code-block:: console
+To run `clang-include-fixer` on a potentially unsaved buffer in Vim. Add the
+following key binding to your `.vimrc`:
- noremap <leader>cf :pyf path/to/llvm/source/clang-tools-extra/clang-include-fixer/tool/clang-include-fixer.py<cr>
+```console
+noremap <leader>cf :pyf path/to/llvm/source/clang-tools-extra/clang-include-fixer/tool/clang-include-fixer.py<cr>
+```
This enables `clang-include-fixer` for NORMAL and VISUAL mode. Change
`<leader>cf` to another binding if you need clang-include-fixer on a
diff erent
-key. The `<leader> key
-<http://vim.wikia.com/wiki/Mapping_keys_in_Vim_-_Tutorial_(Part_3)#Map_leader>`_
+key. The [\<leader> key](<http://vim.wikia.com/wiki/Mapping_keys_in_Vim_-_Tutorial_(Part_3)#Map_leader>)
is a reference to a specific key defined by the mapleader variable and is bound
to backslash by default.
-Make sure vim can find :program:`clang-include-fixer`:
+Make sure vim can find {program}`clang-include-fixer`:
-- Add the path to :program:`clang-include-fixer` to the PATH environment variable.
-- Or set ``g:clang_include_fixer_path`` in vimrc: ``let g:clang_include_fixer_path=path/to/clang-include-fixer``
+- Add the path to {program}`clang-include-fixer` to the PATH environment variable.
+- Or set `g:clang_include_fixer_path` in vimrc: `let g:clang_include_fixer_path=path/to/clang-include-fixer`
You can customize the number of headers being shown by setting
-``let g:clang_include_fixer_maximum_suggested_headers=5``
+`let g:clang_include_fixer_maximum_suggested_headers=5`
Customized settings in `.vimrc`:
-- ``let g:clang_include_fixer_path = "clang-include-fixer"``
+- `let g:clang_include_fixer_path = "clang-include-fixer"`
Set clang-include-fixer binary file path.
-- ``let g:clang_include_fixer_maximum_suggested_headers = 3``
+- `let g:clang_include_fixer_maximum_suggested_headers = 3`
- Set the maximum number of ``#includes`` to show. Default is 3.
+ Set the maximum number of `#includes` to show. Default is 3.
-- ``let g:clang_include_fixer_increment_num = 5``
+- `let g:clang_include_fixer_increment_num = 5`
- Set the increment number of #includes to show every time when pressing ``m``.
+ Set the increment number of #includes to show every time when pressing `m`.
Default is 5.
-- ``let g:clang_include_fixer_jump_to_include = 0``
+- `let g:clang_include_fixer_jump_to_include = 0`
- Set to 1 if you want to jump to the new inserted ``#include`` line. Default is
+ Set to 1 if you want to jump to the new inserted `#include` line. Default is
0.
-- ``let g:clang_include_fixer_query_mode = 0``
+- `let g:clang_include_fixer_query_mode = 0`
- Set to 1 if you want to insert ``#include`` for the symbol under the cursor.
+ Set to 1 if you want to insert `#include` for the symbol under the cursor.
Default is 0. Compared to normal mode, this mode won't parse the source file
and only search the symbol from database, which is faster than normal mode.
-See ``clang-include-fixer.py`` for more details.
+See `clang-include-fixer.py` for more details.
-Integrate with Emacs
---------------------
-To run `clang-include-fixer` on a potentially unsaved buffer in Emacs.
-Ensure that Emacs finds ``clang-include-fixer.el`` by adding the directory
-containing the file to the ``load-path`` and requiring the `clang-include-fixer`
-in your ``.emacs``:
+### Integrate with Emacs
-.. code-block:: console
+To run `clang-include-fixer` on a potentially unsaved buffer in Emacs.
+Ensure that Emacs finds `clang-include-fixer.el` by adding the directory
+containing the file to the `load-path` and requiring the `clang-include-fixer`
+in your `.emacs`:
- (add-to-list 'load-path "path/to/llvm/source/clang-tools-extra/clang-include-fixer/tool/"
- (require 'clang-include-fixer)
+```console
+(add-to-list 'load-path "path/to/llvm/source/clang-tools-extra/clang-include-fixer/tool/"
+(require 'clang-include-fixer)
+```
Within Emacs the tool can be invoked with the command
-``M-x clang-include-fixer``. This will insert the header that defines the
+`M-x clang-include-fixer`. This will insert the header that defines the
first undefined symbol; if there is more than one header that would define the
symbol, the user is prompted to select one.
To include the header that defines the symbol at point, run
-``M-x clang-include-fixer-at-point``.
+`M-x clang-include-fixer-at-point`.
-Make sure Emacs can find :program:`clang-include-fixer`:
+Make sure Emacs can find {program}`clang-include-fixer`:
-- Either add the parent directory of :program:`clang-include-fixer` to the PATH
+- Either add the parent directory of {program}`clang-include-fixer` to the PATH
environment variable, or customize the Emacs user option
- ``clang-include-fixer-executable`` to point to the file name of the program.
+ `clang-include-fixer-executable` to point to the file name of the program.
-How it Works
-============
+## How it Works
To get the most information out of Clang at parse time,
-:program:`clang-include-fixer` runs in tandem with the parse and receives
+{program}`clang-include-fixer` runs in tandem with the parse and receives
callbacks from Clang's semantic analysis. In particular it reuses the existing
support for typo corrections. Whenever Clang tries to correct a potential typo
it emits a callback to the include fixer which then looks for a corresponding
@@ -150,6 +143,8 @@ The identifier that should be typo corrected is then sent to the database, if a
header file is returned it is added as an include directive at the top of the
file.
-Currently :program:`clang-include-fixer` only inserts a single include at a
+Currently {program}`clang-include-fixer` only inserts a single include at a
time to avoid getting caught in follow-up errors. If multiple `#include`
additions are desired the program can be rerun until a fix-point is reached.
+
+[how to setup tooling for llvm]: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
diff --git a/clang-tools-extra/docs/clang-modernize.md b/clang-tools-extra/docs/clang-modernize.md
index 0a4296118926c..646bdf3a017e3 100644
--- a/clang-tools-extra/docs/clang-modernize.md
+++ b/clang-tools-extra/docs/clang-modernize.md
@@ -1,4 +1,6 @@
-:orphan:
+---
+orphan: true
+---
-All :program:`clang-modernize` transforms have moved to :doc:`clang-tidy/index`
-(see the ``modernize`` module).
+All {program}`clang-modernize` transforms have moved to {doc}`clang-tidy/index`
+(see the `modernize` module).
diff --git a/clang-tools-extra/docs/clang-reorder-fields.md b/clang-tools-extra/docs/clang-reorder-fields.md
index 1e09328872170..632583e90feaa 100644
--- a/clang-tools-extra/docs/clang-reorder-fields.md
+++ b/clang-tools-extra/docs/clang-reorder-fields.md
@@ -1,13 +1,13 @@
-====================
-Clang-Reorder-Fields
-====================
+# Clang-Reorder-Fields
-.. contents::
+```{contents}
+```
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
+```
-:program:`clang-reorder-fields` is a refactoring tool to reorder fields in
+{program}`clang-reorder-fields` is a refactoring tool to reorder fields in
C/C++ structs and classes. This tool automatically updates:
- Field declarations in the record definition
@@ -18,255 +18,243 @@ C/C++ structs and classes. This tool automatically updates:
This can be useful for optimizing memory layout, improving cache performance,
or conforming to coding standards that require specific field orderings.
-Example usage
--------------
+## Example usage
-Basic struct reordering
-~~~~~~~~~~~~~~~~~~~~~~~
+### Basic struct reordering
Consider this simple struct in `example.c`:
-.. code-block:: c
-
- struct Foo {
- const int *x;
- int y;
- double z;
- int w;
- };
-
- int main() {
- const int val = 42;
- struct Foo foo = { &val, 0, 1.5, 17 };
- return 0;
- }
+```c
+struct Foo {
+ const int *x;
+ int y;
+ double z;
+ int w;
+};
+
+int main() {
+ const int val = 42;
+ struct Foo foo = { &val, 0, 1.5, 17 };
+ return 0;
+}
+```
To reorder the fields to `z, w, y, x`, run:
-.. code-block:: console
-
- clang-reorder-fields -record-name Foo -fields-order z,w,y,x example.c --
+```console
+clang-reorder-fields -record-name Foo -fields-order z,w,y,x example.c --
+```
This will reorder both the struct definition and the initialization:
-.. code-block:: c
+```c
+struct Foo {
+ double z;
+ int w;
+ int y;
+ const int *x;
+};
- struct Foo {
- double z;
- int w;
- int y;
- const int *x;
- };
+int main() {
+ const int val = 42;
+ struct Foo foo = { 1.5, 17, 0, &val };
+ return 0;
+}
+```
- int main() {
- const int val = 42;
- struct Foo foo = { 1.5, 17, 0, &val };
- return 0;
- }
-
-Namespaced structs
-~~~~~~~~~~~~~~~~~~
+### Namespaced structs
For C++ code with namespaces, use the fully-qualified name:
-.. code-block:: c++
-
- namespace bar {
- struct Foo {
- const int *x;
- int y;
- double z;
- int w;
- };
- }
-
-.. code-block:: console
-
- clang-reorder-fields -record-name ::bar::Foo -fields-order z,w,y,x example.cpp --
+```c++
+namespace bar {
+struct Foo {
+ const int *x;
+ int y;
+ double z;
+ int w;
+};
+}
+```
+
+```console
+clang-reorder-fields -record-name ::bar::Foo -fields-order z,w,y,x example.cpp --
+```
For classes defined in the global namespace (without any namespace), you can
use either the simple class name or prefix it with `::`:
-.. code-block:: console
-
- clang-reorder-fields -record-name Foo -fields-order z,w,y,x example.cpp --
- # or
- clang-reorder-fields -record-name ::Foo -fields-order z,w,y,x example.cpp --
+```console
+clang-reorder-fields -record-name Foo -fields-order z,w,y,x example.cpp --
+# or
+clang-reorder-fields -record-name ::Foo -fields-order z,w,y,x example.cpp --
+```
-C++ constructor initializer lists
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### C++ constructor initializer lists
The tool also reorders constructor initializer lists. Given:
-.. code-block:: c++
-
- class Foo {
- public:
- Foo();
-
- private:
- int x;
- const char *s1;
- const char *s2;
- double z;
- };
-
- Foo::Foo():
- x(12),
- s1("abc"),
- s2("def"),
- z(3.14)
- {}
+```c++
+class Foo {
+public:
+ Foo();
+
+private:
+ int x;
+ const char *s1;
+ const char *s2;
+ double z;
+};
+
+Foo::Foo():
+ x(12),
+ s1("abc"),
+ s2("def"),
+ z(3.14)
+{}
+```
Running:
-.. code-block:: console
-
- clang-reorder-fields -record-name Foo -fields-order s1,x,z,s2 example.cpp --
+```console
+clang-reorder-fields -record-name Foo -fields-order s1,x,z,s2 example.cpp --
+```
Will reorder both the field declarations and the constructor initializers:
-.. code-block:: c++
-
- class Foo {
- public:
- Foo();
+```c++
+class Foo {
+public:
+ Foo();
- private:
- const char *s1;
- int x;
- double z;
- const char *s2;
- };
+private:
+ const char *s1;
+ int x;
+ double z;
+ const char *s2;
+};
- Foo::Foo():
- s1("abc"),
- x(12),
- z(3.14),
- s2("def")
- {}
+Foo::Foo():
+ s1("abc"),
+ x(12),
+ z(3.14),
+ s2("def")
+{}
+```
-Designated initializers
-~~~~~~~~~~~~~~~~~~~~~~~
+### Designated initializers
For C++20 code using designated initializers:
-.. code-block:: c++
-
- struct Bar {
- char a;
- int b;
- int c;
- };
-
- int main() {
- Bar bar1 = { 'a', 0, 123 };
- Bar bar2 = { .a = 'a', .b = 0, .c = 123 };
- return 0;
- }
-
-.. code-block:: console
-
- clang-reorder-fields --extra-arg="-std=c++20" -record-name Bar \
- -fields-order c,a,b example.cpp --
+```c++
+struct Bar {
+ char a;
+ int b;
+ int c;
+};
+
+int main() {
+ Bar bar1 = { 'a', 0, 123 };
+ Bar bar2 = { .a = 'a', .b = 0, .c = 123 };
+ return 0;
+}
+```
+
+```console
+clang-reorder-fields --extra-arg="-std=c++20" -record-name Bar \
+ -fields-order c,a,b example.cpp --
+```
Will produce:
-.. code-block:: c++
+```c++
+struct Bar {
+ int c;
+ char a;
+ int b;
+};
- struct Bar {
- int c;
- char a;
- int b;
- };
+int main() {
+ Bar bar1 = { 123, 'a', 0 };
+ Bar bar2 = { .c = 123, .a = 'a', .b = 0 };
+ return 0;
+}
+```
- int main() {
- Bar bar1 = { 123, 'a', 0 };
- Bar bar2 = { .c = 123, .a = 'a', .b = 0 };
- return 0;
- }
-
-In-place editing
-~~~~~~~~~~~~~~~~
+### In-place editing
Use the `-i` flag to modify files in-place:
-.. code-block:: console
-
- clang-reorder-fields -record-name Foo -fields-order z,w,y,x -i example.c --
+```console
+clang-reorder-fields -record-name Foo -fields-order z,w,y,x -i example.c --
+```
-Limitations and Caveats
------------------------
+## Limitations and Caveats
-Different access specifiers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Different access specifiers
The tool cannot reorder fields with
diff erent access specifiers
-(``public/private/protected``). All fields being reordered must have the same
+(`public/private/protected`). All fields being reordered must have the same
access level.
-.. code-block:: c++
-
- class Example {
- private:
- int x;
- public:
- int y; // Cannot reorder x and y -
diff erent access levels
- };
+```c++
+class Example {
+private:
+ int x;
+public:
+ int y; // Cannot reorder x and y -
diff erent access levels
+};
+```
-Multiple field declarations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Multiple field declarations
Declarations with multiple fields in one statement are not supported:
-.. code-block:: c
+```c
+struct Example {
+ int a, b; // Not supported - multiple fields in one declaration
+};
+```
- struct Example {
- int a, b; // Not supported - multiple fields in one declaration
- };
-
-Macro-expanded fields
-~~~~~~~~~~~~~~~~~~~~~
+### Macro-expanded fields
Macros that expand to multiple field declarations are not supported. However,
macros that expand to a single field declaration work correctly:
-.. code-block:: c
-
- #define INT_FIELD(NAME) int NAME // Supported - expands to one field
- #define TWO_FIELDS int a; int b; // Not supported - expands to two fields
+```c
+#define INT_FIELD(NAME) int NAME // Supported - expands to one field
+#define TWO_FIELDS int a; int b; // Not supported - expands to two fields
- struct Supported {
- INT_FIELD(x); // OK - this is a single field
- int y;
- INT_FIELD(z); // OK - this is a single field
- };
+struct Supported {
+ INT_FIELD(x); // OK - this is a single field
+ int y;
+ INT_FIELD(z); // OK - this is a single field
+};
- struct NotSupported {
- TWO_FIELDS // Not OK - expands to multiple fields
- int c;
- };
+struct NotSupported {
+ TWO_FIELDS // Not OK - expands to multiple fields
+ int c;
+};
+```
The tool can reorder fields declared via macros as long as each macro invocation
expands to exactly one field declaration.
-Preprocessor directives
-~~~~~~~~~~~~~~~~~~~~~~~
+### Preprocessor directives
Structs with preprocessor directives between fields cannot be reordered:
-.. code-block:: c
+```c
+struct Example {
+ int a;
+#ifdef FEATURE
+ int b;
+#endif
+ int c; // Not supported - preprocessor directives present
+};
+```
- struct Example {
- int a;
- #ifdef FEATURE
- int b;
- #endif
- int c; // Not supported - preprocessor directives present
- };
-
-Flexible array members
-~~~~~~~~~~~~~~~~~~~~~~
+### Flexible array members
In C, a flexible array member is an incomplete array type that must be the last
member of a struct (as specified by C99 and later standards). This allows the
@@ -274,62 +262,61 @@ struct to have a variable-length array at the end. Since this is a language
requirement, the tool enforces that flexible array members remain in the last
position:
-.. code-block:: c
-
- struct Example {
- int count;
- int data[]; // Flexible array member - must remain last
- };
+```c
+struct Example {
+ int count;
+ int data[]; // Flexible array member - must remain last
+};
+```
Attempting to reorder fields such that the flexible array member is no longer
last will result in an error:
-.. code-block:: console
-
- clang-reorder-fields -record-name Example -fields-order data,count example.c --
+```console
+clang-reorder-fields -record-name Example -fields-order data,count example.c --
+```
Will produce:
-.. code-block:: text
-
- Flexible array member must remain the last field in the struct
+```text
+Flexible array member must remain the last field in the struct
+```
This ensures the generated code remains valid C.
-Field dependencies in initializers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Field dependencies in initializers
The tool will issue a warning if reordering causes a field to be used in an
initializer before it's initialized. Consider this example:
-.. code-block:: c++
-
- class Foo {
- public:
- Foo(int x, char c);
- int x;
- char c;
- Dummy z;
- };
-
- Foo::Foo(int x, char c) :
- x(x),
- c(c),
- z(this->x, c) // z's initializer uses x and c
- {}
+```c++
+class Foo {
+public:
+ Foo(int x, char c);
+ int x;
+ char c;
+ Dummy z;
+};
+
+Foo::Foo(int x, char c) :
+ x(x),
+ c(c),
+ z(this->x, c) // z's initializer uses x and c
+{}
+```
If you reorder the fields to `z, c, x`:
-.. code-block:: console
-
- clang-reorder-fields -record-name Foo -fields-order z,c,x example.cpp --
+```console
+clang-reorder-fields -record-name Foo -fields-order z,c,x example.cpp --
+```
The tool will produce warnings:
-.. code-block:: text
-
- example.cpp:10:3: warning: reordering field x after z makes x uninitialized when used in init expression
- example.cpp:10:3: warning: reordering field c after z makes c uninitialized when used in init expression
+```text
+example.cpp:10:3: warning: reordering field x after z makes x uninitialized when used in init expression
+example.cpp:10:3: warning: reordering field c after z makes c uninitialized when used in init expression
+```
This warns you that in C++, member initializers are executed in the order that
fields are declared in the class, not the order they appear in the initializer
@@ -339,85 +326,81 @@ tries to use `x` and `c` which haven't been initialized yet.
The tool will still perform the reordering but warns about the potential issue.
You should review these warnings and adjust your code accordingly.
-:program:`clang-reorder-fields` Command Line Options
-----------------------------------------------------
-
-.. option:: --record-name=<string>
-
- The fully-qualified name of the struct or class to reorder. Required.
-
- For C structs, use the struct name directly (e.g., `Foo`).
+## {program}`clang-reorder-fields` Command Line Options
- For C++ classes/structs in namespaces, use the fully-qualified name including
- namespaces (e.g., `::namespace::ClassName`).
+:::{option} --record-name=<string>
+The fully-qualified name of the struct or class to reorder. Required.
- For C++ classes/structs in the global namespace, you can use either the simple
- name (e.g., `Foo`) or prefix with `::` (e.g., `::Foo`).
+For C structs, use the struct name directly (e.g., `Foo`).
-.. option:: --fields-order=<string>
+For C++ classes/structs in namespaces, use the fully-qualified name including
+namespaces (e.g., `::namespace::ClassName`).
- Comma-separated list of field names in the desired order. Required.
+For C++ classes/structs in the global namespace, you can use either the simple
+name (e.g., `Foo`) or prefix with `::` (e.g., `::Foo`).
+:::
- All field names must exactly match the fields in the struct/class definition.
- The number of fields must match the number in the definition.
+:::{option} --fields-order=<string>
+Comma-separated list of field names in the desired order. Required.
-.. option:: -i
+All field names must exactly match the fields in the struct/class definition.
+The number of fields must match the number in the definition.
+:::
- Overwrite edited files in-place. If not specified, the rewritten code is
- printed to stdout.
+:::{option} -i
+Overwrite edited files in-place. If not specified, the rewritten code is
+printed to stdout.
+:::
-.. option:: --extra-arg=<string>
+:::{option} --extra-arg=<string>
+Additional argument to append to the compiler command line.
- Additional argument to append to the compiler command line.
+Useful for specifying language standards (e.g., `--extra-arg="-std=c++20"`).
+:::
- Useful for specifying language standards (e.g., `--extra-arg="-std=c++20"`).
+:::{option} --extra-arg-before=<string>
+Additional argument to prepend to the compiler command line.
+:::
-.. option:: --extra-arg-before=<string>
+:::{option} -p <string>
+Build path. Specifies the directory containing `compile_commands.json` for
+compilation database support.
+:::
- Additional argument to prepend to the compiler command line.
+## Use Cases
-.. option:: -p <string>
-
- Build path. Specifies the directory containing `compile_commands.json` for
- compilation database support.
-
-Use Cases
----------
-
-Memory layout optimization
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Memory layout optimization
Reorder fields to minimize padding and improve cache locality:
-.. code-block:: c
-
- // Before: 24 bytes (with padding)
- struct Data {
- char a; // 1 byte + 7 padding
- double b; // 8 bytes
- char c; // 1 byte + 7 padding
- };
-
-.. code-block:: console
-
- clang-reorder-fields -record-name Data -fields-order b,a,c data.c --
-
-.. code-block:: c
-
- // After: 16 bytes (less padding)
- struct Data {
- double b; // 8 bytes
- char a; // 1 byte
- char c; // 1 byte + 6 padding
- };
-
-Coding standard compliance
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+```c
+// Before: 24 bytes (with padding)
+struct Data {
+ char a; // 1 byte + 7 padding
+ double b; // 8 bytes
+ char c; // 1 byte + 7 padding
+};
+```
+
+```console
+clang-reorder-fields -record-name Data -fields-order b,a,c data.c --
+```
+
+```c
+// After: 16 bytes (less padding)
+struct Data {
+ double b; // 8 bytes
+ char a; // 1 byte
+ char c; // 1 byte + 6 padding
+};
+```
+
+### Coding standard compliance
Ensure fields are ordered according to project conventions (e.g., alphabetically,
by type, or by access pattern).
-Field grouping
-~~~~~~~~~~~~~~
+### Field grouping
Group related fields together for better code organization and readability.
+
diff --git a/clang-tools-extra/docs/clang-tidy.md b/clang-tools-extra/docs/clang-tidy.md
index b9a180690777a..e1bab163a5685 100644
--- a/clang-tools-extra/docs/clang-tidy.md
+++ b/clang-tools-extra/docs/clang-tidy.md
@@ -1,6 +1,10 @@
-:orphan:
+---
+orphan: true
+---
+```{eval-rst}
.. meta::
:http-equiv=refresh: 0;URL='clang-tidy/'
+```
-clang-tidy documentation has moved here: https://clang.llvm.org/extra/clang-tidy/
+clang-tidy documentation has moved here: <https://clang.llvm.org/extra/clang-tidy/>
diff --git a/clang-tools-extra/docs/clangd.md b/clang-tools-extra/docs/clangd.md
index 70bab8354a755..bb8077378681c 100644
--- a/clang-tools-extra/docs/clangd.md
+++ b/clang-tools-extra/docs/clangd.md
@@ -1,3 +1,5 @@
-:orphan:
-:template: clangd_redirect.html
-:redirect_target: https://clangd.llvm.org/
+---
+orphan: true
+redirect_target: https://clangd.llvm.org/
+template: clangd_redirect.html
+---
diff --git a/clang-tools-extra/docs/cpp11-migrate.md b/clang-tools-extra/docs/cpp11-migrate.md
index 0a4296118926c..646bdf3a017e3 100644
--- a/clang-tools-extra/docs/cpp11-migrate.md
+++ b/clang-tools-extra/docs/cpp11-migrate.md
@@ -1,4 +1,6 @@
-:orphan:
+---
+orphan: true
+---
-All :program:`clang-modernize` transforms have moved to :doc:`clang-tidy/index`
-(see the ``modernize`` module).
+All {program}`clang-modernize` transforms have moved to {doc}`clang-tidy/index`
+(see the `modernize` module).
diff --git a/clang-tools-extra/docs/index.md b/clang-tools-extra/docs/index.md
index 55b231c02db6f..0992475e60bbf 100644
--- a/clang-tools-extra/docs/index.md
+++ b/clang-tools-extra/docs/index.md
@@ -1,51 +1,50 @@
-.. title:: Welcome to Extra Clang Tools's documentation!
+```{title} Welcome to Extra Clang Tools's documentation!
+```
+
+# Introduction
-Introduction
-============
Welcome to the clang-tools-extra project which contains extra tools built using
Clang's tooling APIs.
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
+
+ReleaseNotes
+```
- ReleaseNotes
+# Contents
-Contents
-========
-.. toctree::
- :maxdepth: 2
+```{toctree}
+:maxdepth: 2
- clang-tidy/index
- clang-include-fixer
- clang-change-namespace
- clang-reorder-fields
- modularize
- pp-trace
- clangd <https://clangd.llvm.org/>
- clang-doc
- Maintainers
+clang-tidy/index
+clang-include-fixer
+clang-change-namespace
+clang-reorder-fields
+modularize
+pp-trace
+clangd <https://clangd.llvm.org/>
+clang-doc
+Maintainers
+```
+# Doxygen Documentation
-Doxygen Documentation
-=====================
The Doxygen documentation describes the **internal** software that makes up the
tools of clang-tools-extra, not the **external** use of these tools. The Doxygen
documentation contains no instructions about how to use the tools, only the APIs
that make up the software. For usage instructions, please see the user's guide
or reference manual for each tool.
-* `Doxygen documentation`_
-
-.. _`Doxygen documentation`: doxygen/annotated.html
-
-.. note::
- This documentation is generated directly from the source code with doxygen.
- Since the tools of clang-tools-extra are constantly under active
- development, what you're about to read is out of date!
+- <a href="doxygen/annotated.html">Doxygen documentation</a>
+:::{note}
+This documentation is generated directly from the source code with doxygen.
+Since the tools of clang-tools-extra are constantly under active
+development, what you're about to read is out of date!
+:::
-Indices and tables
-==================
+# Indices and tables
-* :ref:`genindex`
-* :ref:`search`
+- {ref}`genindex`
+- {ref}`search`
diff --git a/clang-tools-extra/docs/modularize.md b/clang-tools-extra/docs/modularize.md
index 97fd33b958650..4566333bff043 100644
--- a/clang-tools-extra/docs/modularize.md
+++ b/clang-tools-extra/docs/modularize.md
@@ -1,15 +1,15 @@
-.. index:: modularize
+```{index} modularize
+```
-==================================
-Modularize User's Manual
-==================================
+# Modularize User's Manual
-.. toctree::
- :hidden:
+```{toctree}
+:hidden: true
- ModularizeUsage
+ModularizeUsage
+```
-:program:`modularize` is a standalone tool that checks whether a set of headers
+{program}`modularize` is a standalone tool that checks whether a set of headers
provides the consistent definitions required to use modules. For example, it
detects whether the same entity (say, a NULL macro or size_t typedef) is
defined in multiple headers or whether a header produces
diff erent definitions
@@ -17,102 +17,103 @@ under
diff erent circumstances. These conditions cause modules built from the
headers to behave poorly, and should be fixed before introducing a module
map.
-:program:`modularize` also has an assistant mode option for generating
+{program}`modularize` also has an assistant mode option for generating
a module map file based on the provided header list. The generated file
is a functional module map that can be used as a starting point for a
module.modulemap file.
-Getting Started
-===============
+## Getting Started
To build from source:
-1. Read `Getting Started with the LLVM System`_ and `Clang Tools
- Documentation`_ for information on getting sources for LLVM, Clang, and
+1. Read [Getting Started with the LLVM System][getting started with the llvm system] and [Clang Tools
+ Documentation][clang tools documentation] for information on getting sources for LLVM, Clang, and
Clang Extra Tools.
-2. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give
+2. [Getting Started with the LLVM System][getting started with the llvm system] and [Building LLVM with CMake][building llvm with cmake] give
directions for how to build. With sources all checked out into the
right place the LLVM build will build Clang Extra Tools and their
dependencies automatically.
- * If using CMake, you can also use the ``modularize`` target to build
+ - If using CMake, you can also use the `modularize` target to build
just the modularize tool and its dependencies.
-Before continuing, take a look at :doc:`ModularizeUsage` to see how to invoke
+Before continuing, take a look at {doc}`ModularizeUsage` to see how to invoke
modularize.
-.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
-.. _Building LLVM with CMake: https://llvm.org/docs/CMake.html
-.. _Clang Tools Documentation: https://clang.llvm.org/docs/ClangTools.html
-
-What Modularize Checks
-======================
+## What Modularize Checks
Modularize will check for the following:
-* Duplicate global type and variable definitions
-* Duplicate macro definitions
-* Macro instances, 'defined(macro)', or #if, #elif, #ifdef, #ifndef conditions
+- Duplicate global type and variable definitions
+- Duplicate macro definitions
+- Macro instances, 'defined(macro)', or #if, #elif, #ifdef, #ifndef conditions
that evaluate
diff erently in a header
-* #include directives inside 'extern "C/C++" {}' or 'namespace (name) {}' blocks
-* Module map header coverage completeness (in the case of a module map input
+- #include directives inside 'extern "C/C++" {}' or 'namespace (name) {}' blocks
+- Module map header coverage completeness (in the case of a module map input
only)
Modularize will do normal C/C++ parsing, reporting normal errors and warnings,
-but will also report special error messages like the following::
+but will also report special error messages like the following:
- error: '(symbol)' defined at multiple locations:
- (file):(row):(column)
- (file):(row):(column)
+```
+error: '(symbol)' defined at multiple locations:
+ (file):(row):(column)
+ (file):(row):(column)
- error: header '(file)' has
diff erent contents depending on how it was included
+error: header '(file)' has
diff erent contents depending on how it was included
+```
-The latter might be followed by messages like the following::
+The latter might be followed by messages like the following:
- note: '(symbol)' in (file) at (row):(column) not always provided
+```
+note: '(symbol)' in (file) at (row):(column) not always provided
+```
Checks will also be performed for macro expansions, defined(macro)
expressions, and preprocessor conditional directives that evaluate
-inconsistently, and can produce error messages like the following::
-
- (...)/SubHeader.h:11:5:
- #if SYMBOL == 1
- ^
- error: Macro instance 'SYMBOL' has
diff erent values in this header,
- depending on how it was included.
- 'SYMBOL' expanded to: '1' with respect to these inclusion paths:
- (...)/Header1.h
+inconsistently, and can produce error messages like the following:
+
+```
+ (...)/SubHeader.h:11:5:
+#if SYMBOL == 1
+ ^
+error: Macro instance 'SYMBOL' has
diff erent values in this header,
+ depending on how it was included.
+ 'SYMBOL' expanded to: '1' with respect to these inclusion paths:
+ (...)/Header1.h
+ (...)/SubHeader.h
+(...)/SubHeader.h:3:9:
+#define SYMBOL 1
+ ^
+Macro defined here.
+ 'SYMBOL' expanded to: '2' with respect to these inclusion paths:
+ (...)/Header2.h
(...)/SubHeader.h
- (...)/SubHeader.h:3:9:
- #define SYMBOL 1
- ^
- Macro defined here.
- 'SYMBOL' expanded to: '2' with respect to these inclusion paths:
- (...)/Header2.h
- (...)/SubHeader.h
- (...)/SubHeader.h:7:9:
- #define SYMBOL 2
- ^
- Macro defined here.
+(...)/SubHeader.h:7:9:
+#define SYMBOL 2
+ ^
+Macro defined here.
+```
Checks will also be performed for '#include' directives that are
nested inside 'extern "C/C++" {}' or 'namespace (name) {}' blocks,
-and can produce error message like the following::
+and can produce error message like the following:
- IncludeInExtern.h:2:3:
- #include "Empty.h"
- ^
- error: Include directive within extern "C" {}.
- IncludeInExtern.h:1:1:
- extern "C" {
- ^
- The "extern "C" {}" block is here.
+```
+IncludeInExtern.h:2:3:
+#include "Empty.h"
+^
+error: Include directive within extern "C" {}.
+IncludeInExtern.h:1:1:
+extern "C" {
+^
+The "extern "C" {}" block is here.
+```
-.. _module-map-coverage:
+(module-map-coverage)=
-Module Map Coverage Check
-=========================
+## Module Map Coverage Check
The coverage check uses the Clang library to read and parse the
module map file. Starting at the module map file directory, or just the
@@ -134,48 +135,99 @@ can be included on the command line after the module map file argument.
Warning message have the form:
- warning: module.modulemap does not account for file: Level3A.h
+> warning: module.modulemap does not account for file: Level3A.h
Note that for the case of the module map referencing a file that does
not exist, the module map parser in Clang will (at the time of this
writing) display an error message.
-To limit the checks :program:`modularize` does to just the module
-map coverage check, use the ``-coverage-check-only option``.
+To limit the checks {program}`modularize` does to just the module
+map coverage check, use the `-coverage-check-only option`.
-For example::
+For example:
- modularize -coverage-check-only module.modulemap
+```
+modularize -coverage-check-only module.modulemap
+```
-.. _module-map-generation:
+(module-map-generation)=
-Module Map Generation
-=====================
+## Module Map Generation
-If you specify the ``-module-map-path=<module map file>``,
-:program:`modularize` will output a module map based on the input header list.
+If you specify the `-module-map-path=<module map file>`,
+{program}`modularize` will output a module map based on the input header list.
A module will be created for each header. Also, if the header in the header
list is a partial path, a nested module hierarchy will be created in which a
module will be created for each subdirectory component in the header path,
with the header itself represented by the innermost module. If other headers
use the same subdirectories, they will be enclosed in these same modules also.
-For example, for the header list::
+For example, for the header list:
+
+```
+SomeTypes.h
+SomeDecls.h
+SubModule1/Header1.h
+SubModule1/Header2.h
+SubModule2/Header3.h
+SubModule2/Header4.h
+SubModule2.h
+```
+
+The following module map will be generated:
+
+```
+// Output/NoProblemsAssistant.txt
+// Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \
+ -root-module=Root NoProblemsAssistant.modularize
+
+module SomeTypes {
+ header "SomeTypes.h"
+ export *
+}
+module SomeDecls {
+ header "SomeDecls.h"
+ export *
+}
+module SubModule1 {
+ module Header1 {
+ header "SubModule1/Header1.h"
+ export *
+ }
+ module Header2 {
+ header "SubModule1/Header2.h"
+ export *
+ }
+}
+module SubModule2 {
+ module Header3 {
+ header "SubModule2/Header3.h"
+ export *
+ }
+ module Header4 {
+ header "SubModule2/Header4.h"
+ export *
+ }
+ header "SubModule2.h"
+ export *
+}
+```
- SomeTypes.h
- SomeDecls.h
- SubModule1/Header1.h
- SubModule1/Header2.h
- SubModule2/Header3.h
- SubModule2/Header4.h
- SubModule2.h
+An optional `-root-module=<root-name>` option can be used to cause a root module
+to be created which encloses all the modules.
-The following module map will be generated::
+An optional `-problem-files-list=<problem-file-name>` can be used to input
+a list of files to be excluded, perhaps as a temporary stop-gap measure until
+problem headers can be fixed.
- // Output/NoProblemsAssistant.txt
- // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \
- -root-module=Root NoProblemsAssistant.modularize
+For example, with the same header list from above:
+```
+// Output/NoProblemsAssistant.txt
+// Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \
+ -root-module=Root NoProblemsAssistant.modularize
+
+module Root {
module SomeTypes {
header "SomeTypes.h"
export *
@@ -206,60 +258,20 @@ The following module map will be generated::
header "SubModule2.h"
export *
}
-
-An optional ``-root-module=<root-name>`` option can be used to cause a root module
-to be created which encloses all the modules.
-
-An optional ``-problem-files-list=<problem-file-name>`` can be used to input
-a list of files to be excluded, perhaps as a temporary stop-gap measure until
-problem headers can be fixed.
-
-For example, with the same header list from above::
-
- // Output/NoProblemsAssistant.txt
- // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \
- -root-module=Root NoProblemsAssistant.modularize
-
- module Root {
- module SomeTypes {
- header "SomeTypes.h"
- export *
- }
- module SomeDecls {
- header "SomeDecls.h"
- export *
- }
- module SubModule1 {
- module Header1 {
- header "SubModule1/Header1.h"
- export *
- }
- module Header2 {
- header "SubModule1/Header2.h"
- export *
- }
- }
- module SubModule2 {
- module Header3 {
- header "SubModule2/Header3.h"
- export *
- }
- module Header4 {
- header "SubModule2/Header4.h"
- export *
- }
- header "SubModule2.h"
- export *
- }
- }
+}
+```
Note that headers with dependents will be ignored with a warning, as the
Clang module mechanism doesn't support headers that rely on other headers
being included first.
The module map format defines some keywords which can't be used in module
-names. If a header has one of these names, an underscore ('_') will be
-prepended to the name. For example, if the header name is ``header.h``,
-because ``header`` is a keyword, the module name will be ``_header``.
+names. If a header has one of these names, an underscore ('\_') will be
+prepended to the name. For example, if the header name is `header.h`,
+because `header` is a keyword, the module name will be `_header`.
For a list of the module map keywords, please see:
-`Lexical structure <https://clang.llvm.org/docs/Modules.html#lexical-structure>`_
+[Lexical structure](https://clang.llvm.org/docs/Modules.html#lexical-structure)
+
+[building llvm with cmake]: https://llvm.org/docs/CMake.html
+[clang tools documentation]: https://clang.llvm.org/docs/ClangTools.html
+[getting started with the llvm system]: https://llvm.org/docs/GettingStarted.html
diff --git a/clang-tools-extra/docs/pp-trace.md b/clang-tools-extra/docs/pp-trace.md
index 1e520bb4ef0b6..21b7588703483 100644
--- a/clang-tools-extra/docs/pp-trace.md
+++ b/clang-tools-extra/docs/pp-trace.md
@@ -1,126 +1,125 @@
-.. index:: pp-trace
+```{index} pp-trace
+```
-==================================
-pp-trace User's Manual
-==================================
+# pp-trace User's Manual
-.. toctree::
- :hidden:
+```{toctree}
+:hidden: true
+```
-:program:`pp-trace` is a standalone tool that traces preprocessor
+{program}`pp-trace` is a standalone tool that traces preprocessor
activity. It's also used as a test of Clang's PPCallbacks interface.
It runs a given source file through the Clang preprocessor, displaying
selected information from callback functions overridden in a
-`PPCallbacks <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html>`_
+[PPCallbacks](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html)
derivation. The output is in a high-level YAML format, described in
-:ref:`OutputFormat`.
+{ref}`OutputFormat`.
-.. _Usage:
+(usage)=
-pp-trace Usage
-==============
+## pp-trace Usage
-Command Line Format
--------------------
+### Command Line Format
-``pp-trace [<pp-trace-options>] <source-file> [-- <front-end-options>]``
+`pp-trace [<pp-trace-options>] <source-file> [-- <front-end-options>]`
-``<pp-trace-options>`` is a place-holder for options
+`<pp-trace-options>` is a place-holder for options
specific to pp-trace, which are described below in
-:ref:`CommandLineOptions`.
-
-``<source-file>`` specifies the source file to run through the preprocessor.
-
-``<front-end-options>`` is a place-holder for regular
-`Clang Compiler Options <https://clang.llvm.org/docs/UsersManual.html#command-line-options>`_,
-which must follow the <source-file>.
-
-.. _CommandLineOptions:
-
-Command Line Options
---------------------
-
-.. option:: -callbacks <comma-separated-globs>
-
- This option specifies a comma-separated list of globs describing the list of
- callbacks that should be traced. Globs are processed in order of appearance.
- Positive globs add matched callbacks to the set, negative globs (those with
- the '-' prefix) remove callacks from the set.
-
- * FileChanged
- * FileSkipped
- * InclusionDirective
- * moduleImport
- * EndOfMainFile
- * Ident
- * PragmaDirective
- * PragmaComment
- * PragmaDetectMismatch
- * PragmaDebug
- * PragmaMessage
- * PragmaDiagnosticPush
- * PragmaDiagnosticPop
- * PragmaDiagnostic
- * PragmaOpenCLExtension
- * PragmaWarning
- * PragmaWarningPush
- * PragmaWarningPop
- * MacroExpands
- * MacroDefined
- * MacroUndefined
- * Defined
- * SourceRangeSkipped
- * If
- * Elif
- * Ifdef
- * Ifndef
- * Else
- * Endif
-
-.. option:: -output <output-file>
-
- By default, pp-trace outputs the trace information to stdout. Use this
- option to output the trace information to a file.
-
-.. _OutputFormat:
-
-pp-trace Output Format
-======================
-
-The pp-trace output is formatted as YAML. See https://yaml.org/ for general
+{ref}`CommandLineOptions`.
+
+`<source-file>` specifies the source file to run through the preprocessor.
+
+`<front-end-options>` is a place-holder for regular
+[Clang Compiler Options](https://clang.llvm.org/docs/UsersManual.html#command-line-options),
+which must follow the \<source-file>.
+
+(commandlineoptions)=
+
+### Command Line Options
+
+:::{option} -callbacks <comma-separated-globs>
+This option specifies a comma-separated list of globs describing the list of
+callbacks that should be traced. Globs are processed in order of appearance.
+Positive globs add matched callbacks to the set, negative globs (those with
+the '-' prefix) remove callacks from the set.
+
+- FileChanged
+- FileSkipped
+- InclusionDirective
+- moduleImport
+- EndOfMainFile
+- Ident
+- PragmaDirective
+- PragmaComment
+- PragmaDetectMismatch
+- PragmaDebug
+- PragmaMessage
+- PragmaDiagnosticPush
+- PragmaDiagnosticPop
+- PragmaDiagnostic
+- PragmaOpenCLExtension
+- PragmaWarning
+- PragmaWarningPush
+- PragmaWarningPop
+- MacroExpands
+- MacroDefined
+- MacroUndefined
+- Defined
+- SourceRangeSkipped
+- If
+- Elif
+- Ifdef
+- Ifndef
+- Else
+- Endif
+:::
+
+:::{option} -output <output-file>
+By default, pp-trace outputs the trace information to stdout. Use this
+option to output the trace information to a file.
+:::
+
+(outputformat)=
+
+## pp-trace Output Format
+
+The pp-trace output is formatted as YAML. See <https://yaml.org/> for general
YAML information. It's arranged as a sequence of information about the
callback call, including the callback name and argument information, for
-example:::
-
- ---
- - Callback: Name
- Argument1: Value1
- Argument2: Value2
+example:
+
+```yaml
+---
+- Callback: Name
+ Argument1: Value1
+ Argument2: Value2
+(etc.)
+...
+```
+
+With real data:
+
+```yaml
+---
+- Callback: FileChanged
+ Loc: "c:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"
+ Reason: EnterFile
+ FileType: C_User
+ PrevFID: (invalid)
(etc.)
- ...
-
-With real data:::
-
- ---
- - Callback: FileChanged
- Loc: "c:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"
- Reason: EnterFile
- FileType: C_User
- PrevFID: (invalid)
- (etc.)
- - Callback: FileChanged
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:5:1"
- Reason: ExitFile
- FileType: C_User
- PrevFID: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/Input/Level1B.h"
- - Callback: EndOfMainFile
- ...
+- Callback: FileChanged
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:5:1"
+ Reason: ExitFile
+ FileType: C_User
+ PrevFID: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/Input/Level1B.h"
+- Callback: EndOfMainFile
+...
+```
In all but one case (MacroDirective) the "Argument" scalars have the same
name as the argument in the corresponding PPCallbacks callback function.
-Callback Details
-----------------
+### Callback Details
The following sections describe the purpose and output format for each callback.
@@ -149,8 +148,7 @@ Note that in some cases, such as when a structure pointer is an argument
value, only some key member or members are shown to represent the value,
instead of trying to display all members of the structure.
-`FileChanged <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a7cc8cfaf34114fc65e92af621cd6464e>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [FileChanged](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a7cc8cfaf34114fc65e92af621cd6464e) Callback
FileChanged is called when the preprocessor enters or exits a file, both the
top level file being compiled, as well as any #include directives. It will
@@ -159,646 +157,618 @@ of a file.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Reason (EnterFile|ExitFile|SystemHeaderPragma|RenameFile) PPCallbacks::FileChangeReason Reason for change.
-FileType (C_User|C_System|C_ExternCSystem) SrcMgr::CharacteristicKind Include type.
-PrevFID ((file)|(invalid)) FileID Previous file, if any.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | ----------------------------------------------------- | ----------------------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Reason | (EnterFile\|ExitFile\|SystemHeaderPragma\|RenameFile) | PPCallbacks::FileChangeReason | Reason for change. |
+| FileType | (C_User\|C_System\|C_ExternCSystem) | SrcMgr::CharacteristicKind | Include type. |
+| PrevFID | ((file)\|(invalid)) | FileID | Previous file, if any. |
-Example:::
+Example:
- - Callback: FileChanged
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"
- Reason: EnterFile
- FileType: C_User
- PrevFID: (invalid)
+```yaml
+- Callback: FileChanged
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"
+ Reason: EnterFile
+ FileType: C_User
+ PrevFID: (invalid)
+```
-`FileSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab5b338a0670188eb05fa7685bbfb5128>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [FileSkipped](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab5b338a0670188eb05fa7685bbfb5128) Callback
FileSkipped is called when a source file is skipped as the result of header
guard optimization.
Argument descriptions:
-============== ================================================== ============================== ========================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ========================================================
-ParentFile ("(file)" or (null)) const FileEntry The file that #included the skipped file.
-FilenameTok (token) const Token The token in ParentFile that indicates the skipped file.
-FileType (C_User|C_System|C_ExternCSystem) SrcMgr::CharacteristicKind The file type.
-============== ================================================== ============================== ========================================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | ----------------------------------- | -------------------------- | -------------------------------------------------------- |
+| ParentFile | ("(file)" or (null)) | const FileEntry | The file that #included the skipped file. |
+| FilenameTok | (token) | const Token | The token in ParentFile that indicates the skipped file. |
+| FileType | (C_User\|C_System\|C_ExternCSystem) | SrcMgr::CharacteristicKind | The file type. |
-Example:::
+Example:
- - Callback: FileSkipped
- ParentFile: "/path/filename.h"
- FilenameTok: "filename.h"
- FileType: C_User
+```yaml
+- Callback: FileSkipped
+ ParentFile: "/path/filename.h"
+ FilenameTok: "filename.h"
+ FileType: C_User
+```
-`InclusionDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a557d9738c329793513a6f57d6b60de52>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [InclusionDirective](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a557d9738c329793513a6f57d6b60de52) Callback
-InclusionDirective is called when an inclusion directive of any kind (#include</code>, #import</code>, etc.) has been processed, regardless of whether the inclusion will actually result in an inclusion.
+InclusionDirective is called when an inclusion directive of any kind (#include\</code>, #import\</code>, etc.) has been processed, regardless of whether the inclusion will actually result in an inclusion.
Argument descriptions:
-============== ================================================== ============================== ============================================================================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ============================================================================================================
-HashLoc "(file):(line):(col)" SourceLocation The location of the '#' that starts the inclusion directive.
-IncludeTok (token) const Token The token that indicates the kind of inclusion directive, e.g., 'include' or 'import'.
-FileName "(file)" StringRef The name of the file being included, as written in the source code.
-IsAngled (true|false) bool Whether the file name was enclosed in angle brackets; otherwise, it was enclosed in quotes.
-FilenameRange "(file)" CharSourceRange The character range of the quotes or angle brackets for the written file name.
-File "(file)" const FileEntry The actual file that may be included by this inclusion directive.
-SearchPath "(path)" StringRef Contains the search path which was used to find the file in the file system.
-RelativePath "(path)" StringRef The path relative to SearchPath, at which the include file was found.
-Imported ((module name)|(null)) const Module The module, whenever an inclusion directive was automatically turned into a module import or null otherwise.
-============== ================================================== ============================== ============================================================================================================
-
-Example:::
-
- - Callback: InclusionDirective
- HashLoc: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:4:1"
- IncludeTok: include
- FileName: "Input/Level1B.h"
- IsAngled: false
- FilenameRange: "Input/Level1B.h"
- File: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/Input/Level1B.h"
- SearchPath: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace"
- RelativePath: "Input/Level1B.h"
- Imported: (null)
-
-`moduleImport <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#af32dcf1b8b7c179c7fcd3e24e89830fe>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
+| HashLoc | "(file):(line):(col)" | SourceLocation | The location of the '#' that starts the inclusion directive. |
+| IncludeTok | (token) | const Token | The token that indicates the kind of inclusion directive, e.g., 'include' or 'import'. |
+| FileName | "(file)" | StringRef | The name of the file being included, as written in the source code. |
+| IsAngled | (true\|false) | bool | Whether the file name was enclosed in angle brackets; otherwise, it was enclosed in quotes. |
+| FilenameRange | "(file)" | CharSourceRange | The character range of the quotes or angle brackets for the written file name. |
+| File | "(file)" | const FileEntry | The actual file that may be included by this inclusion directive. |
+| SearchPath | "(path)" | StringRef | Contains the search path which was used to find the file in the file system. |
+| RelativePath | "(path)" | StringRef | The path relative to SearchPath, at which the include file was found. |
+| Imported | ((module name)\|(null)) | const Module | The module, whenever an inclusion directive was automatically turned into a module import or null otherwise. |
+
+Example:
+
+```yaml
+- Callback: InclusionDirective
+ HashLoc: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:4:1"
+ IncludeTok: include
+ FileName: "Input/Level1B.h"
+ IsAngled: false
+ FilenameRange: "Input/Level1B.h"
+ File: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/Input/Level1B.h"
+ SearchPath: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace"
+ RelativePath: "Input/Level1B.h"
+ Imported: (null)
+```
+
+#### [moduleImport](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#af32dcf1b8b7c179c7fcd3e24e89830fe) Callback
moduleImport is called when there was an explicit module-import syntax.
Argument descriptions:
-============== ================================================== ============================== ===========================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ===========================================================
-ImportLoc "(file):(line):(col)" SourceLocation The location of import directive token.
-Path "(path)" ModuleIdPath The identifiers (and their locations) of the module "path".
-Imported ((module name)|(null)) const Module The imported module; can be null if importing failed.
-============== ================================================== ============================== ===========================================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | ----------------------- | -------------- | ----------------------------------------------------------- |
+| ImportLoc | "(file):(line):(col)" | SourceLocation | The location of import directive token. |
+| Path | "(path)" | ModuleIdPath | The identifiers (and their locations) of the module "path". |
+| Imported | ((module name)\|(null)) | const Module | The imported module; can be null if importing failed. |
-Example:::
+Example:
- - Callback: moduleImport
- ImportLoc: "d:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:2"
- Path: [{Name: Level1B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:9"}, {Name: Level2B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:17"}]
- Imported: Level2B
+```yaml
+- Callback: moduleImport
+ ImportLoc: "d:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:2"
+ Path: [{Name: Level1B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:9"}, {Name: Level2B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:17"}]
+ Imported: Level2B
+```
-`EndOfMainFile <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a63e170d069e99bc1c9c7ea0f3bed8bcc>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [EndOfMainFile](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a63e170d069e99bc1c9c7ea0f3bed8bcc) Callback
EndOfMainFile is called when the end of the main file is reached.
Argument descriptions:
-============== ================================================== ============================== ======================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ======================
-(no arguments)
-============== ================================================== ============================== ======================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | --------------------- | -------------- | ----------- |
+| (no arguments) | | | |
-Example:::
+Example:
- - Callback: EndOfMainFile
+```yaml
+- Callback: EndOfMainFile
+```
-`Ident <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3683f1d1fa513e9b6193d446a5cc2b66>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [Ident](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3683f1d1fa513e9b6193d446a5cc2b66) Callback
Ident is called when a #ident or #sccs directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-str (name) const std::string The text of the directive.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | ----------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| str | (name) | const std::string | The text of the directive. |
-Example:::
+Example:
- - Callback: Ident
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-ident.cpp:3:1"
- str: "$Id$"
+```yaml
+- Callback: Ident
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-ident.cpp:3:1"
+ str: "$Id$"
+```
-`PragmaDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0a2d7a72c62184b3cbde31fb62c6f2f7>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaDirective](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0a2d7a72c62184b3cbde31fb62c6f2f7) Callback
PragmaDirective is called when start reading any pragma directive.
Argument descriptions:
-============== ================================================== ============================== =================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== =================================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Introducer (PIK_HashPragma|PIK__Pragma|PIK___pragma) PragmaIntroducerKind The type of the pragma directive.
-============== ================================================== ============================== =================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | ------------------------------------------------ | -------------------- | --------------------------------- |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Introducer | (PIK_HashPragma\|PIK\_\_Pragma\|PIK\_\_\_pragma) | PragmaIntroducerKind | The type of the pragma directive. |
-Example:::
+Example:
- - Callback: PragmaDirective
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- Introducer: PIK_HashPragma
+```yaml
+- Callback: PragmaDirective
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ Introducer: PIK_HashPragma
+```
-`PragmaComment <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ace0d940fc2c12ab76441466aab58dc37>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaComment](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ace0d940fc2c12ab76441466aab58dc37) Callback
PragmaComment is called when a #pragma comment directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Kind ((name)|(null)) const IdentifierInfo The comment kind symbol.
-Str (message directive) const std::string The comment message directive.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Kind | ((name)\|(null)) | const IdentifierInfo | The comment kind symbol. |
+| Str | (message directive) | const std::string | The comment message directive. |
-Example:::
+Example:
- - Callback: PragmaComment
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- Kind: library
- Str: kernel32.lib
+```yaml
+- Callback: PragmaComment
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ Kind: library
+ Str: kernel32.lib
+```
-`PragmaDetectMismatch <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab11158c9149fb8ad8af1903f4a6cd65d>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaDetectMismatch](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab11158c9149fb8ad8af1903f4a6cd65d) Callback
PragmaDetectMismatch is called when a #pragma detect_mismatch directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Name "(name)" const std::string The name.
-Value (string) const std::string The value.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | ----------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Name | "(name)" | const std::string | The name. |
+| Value | (string) | const std::string | The value. |
-Example:::
+Example:
- - Callback: PragmaDetectMismatch
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- Name: name
- Value: value
+```yaml
+- Callback: PragmaDetectMismatch
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ Name: name
+ Value: value
+```
-`PragmaDebug <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a57cdccb6dcc07e926513ac3d5b121466>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaDebug](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a57cdccb6dcc07e926513ac3d5b121466) Callback
-PragmaDebug is called when a #pragma clang __debug directive is read.
+PragmaDebug is called when a #pragma clang \_\_debug directive is read.
Argument descriptions:
-============== ================================================== ============================== ================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ================================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-DebugType (string) StringRef Indicates type of debug message.
-============== ================================================== ============================== ================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------- | -------------------------------- |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| DebugType | (string) | StringRef | Indicates type of debug message. |
-Example:::
+Example:
- - Callback: PragmaDebug
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- DebugType: warning
+```yaml
+- Callback: PragmaDebug
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ DebugType: warning
+```
-`PragmaMessage <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abb42935d9a9fd8e2c4f51cfdc4ea2ae1>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaMessage](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abb42935d9a9fd8e2c4f51cfdc4ea2ae1) Callback
PragmaMessage is called when a #pragma message directive is read.
Argument descriptions:
-============== ================================================== ============================== =======================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== =======================================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Namespace (name) StringRef The namespace of the message directive.
-Kind (PMK_Message|PMK_Warning|PMK_Error) PPCallbacks::PragmaMessageKind The type of the message directive.
-Str (string) StringRef The text of the message directive.
-============== ================================================== ============================== =======================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | ------------------------------------- | ------------------------------ | --------------------------------------- |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Namespace | (name) | StringRef | The namespace of the message directive. |
+| Kind | (PMK_Message\|PMK_Warning\|PMK_Error) | PPCallbacks::PragmaMessageKind | The type of the message directive. |
+| Str | (string) | StringRef | The text of the message directive. |
-Example:::
+Example:
- - Callback: PragmaMessage
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- Namespace: "GCC"
- Kind: PMK_Message
- Str: The message text.
+```yaml
+- Callback: PragmaMessage
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ Namespace: "GCC"
+ Kind: PMK_Message
+ Str: The message text.
+```
-`PragmaDiagnosticPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0f3ff19762baa38fe6c5c58022d32979>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaDiagnosticPush](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0f3ff19762baa38fe6c5c58022d32979) Callback
PragmaDiagnosticPush is called when a #pragma gcc diagnostic push directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Namespace (name) StringRef Namespace name.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Namespace | (name) | StringRef | Namespace name. |
-Example:::
+Example:
- - Callback: PragmaDiagnosticPush
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- Namespace: "GCC"
+```yaml
+- Callback: PragmaDiagnosticPush
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ Namespace: "GCC"
+```
-`PragmaDiagnosticPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac94d789873122221fba8d76f6c5ea45e>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaDiagnosticPop](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac94d789873122221fba8d76f6c5ea45e) Callback
PragmaDiagnosticPop is called when a #pragma gcc diagnostic pop directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Namespace (name) StringRef Namespace name.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Namespace | (name) | StringRef | Namespace name. |
-Example:::
+Example:
- - Callback: PragmaDiagnosticPop
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- Namespace: "GCC"
+```yaml
+- Callback: PragmaDiagnosticPop
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ Namespace: "GCC"
+```
-`PragmaDiagnostic <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afe7938f38a83cb7b4b25a13edfdd7bdd>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaDiagnostic](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afe7938f38a83cb7b4b25a13edfdd7bdd) Callback
PragmaDiagnostic is called when a #pragma gcc diagnostic directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Namespace (name) StringRef Namespace name.
-mapping (0|MAP_IGNORE|MAP_WARNING|MAP_ERROR|MAP_FATAL) diag::Severity Mapping type.
-Str (string) StringRef Warning/error name.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | -------------------------------------------------- | -------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Namespace | (name) | StringRef | Namespace name. |
+| mapping | (0\|MAP_IGNORE\|MAP_WARNING\|MAP_ERROR\|MAP_FATAL) | diag::Severity | Mapping type. |
+| Str | (string) | StringRef | Warning/error name. |
-Example:::
+Example:
- - Callback: PragmaDiagnostic
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- Namespace: "GCC"
- mapping: MAP_WARNING
- Str: WarningName
+```yaml
+- Callback: PragmaDiagnostic
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ Namespace: "GCC"
+ mapping: MAP_WARNING
+ Str: WarningName
+```
-`PragmaOpenCLExtension <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a92a20a21fadbab4e2c788f4e27fe07e7>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaOpenCLExtension](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a92a20a21fadbab4e2c788f4e27fe07e7) Callback
PragmaOpenCLExtension is called when OpenCL extension is either disabled or enabled with a pragma.
Argument descriptions:
-============== ================================================== ============================== ==========================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==========================
-NameLoc "(file):(line):(col)" SourceLocation The location of the name.
-Name (name) const IdentifierInfo Name symbol.
-StateLoc "(file):(line):(col)" SourceLocation The location of the state.
-State (1|0) unsigned Enabled/disabled state.
-============== ================================================== ============================== ==========================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------------- | -------------------------- |
+| NameLoc | "(file):(line):(col)" | SourceLocation | The location of the name. |
+| Name | (name) | const IdentifierInfo | Name symbol. |
+| StateLoc | "(file):(line):(col)" | SourceLocation | The location of the state. |
+| State | (1\|0) | unsigned | Enabled/disabled state. |
-Example:::
+Example:
- - Callback: PragmaOpenCLExtension
- NameLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:10"
- Name: Name
- StateLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:18"
- State: 1
+```yaml
+- Callback: PragmaOpenCLExtension
+ NameLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:10"
+ Name: Name
+ StateLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:18"
+ State: 1
+```
-`PragmaWarning <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#aa17169d25fa1cf0a6992fc944d1d8730>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaWarning](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#aa17169d25fa1cf0a6992fc944d1d8730) Callback
PragmaWarning is called when a #pragma warning directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-WarningSpec (string) StringRef The warning specifier.
-Ids [(number)[, ...]] ArrayRef<int> The warning numbers.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| WarningSpec | (string) | StringRef | The warning specifier. |
+| Ids | \[(number)[, ...]\] | ArrayRef\<int> | The warning numbers. |
-Example:::
+Example:
- - Callback: PragmaWarning
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- WarningSpec: disable
- Ids: 1,2,3
+```yaml
+- Callback: PragmaWarning
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ WarningSpec: disable
+ Ids: 1,2,3
+```
-`PragmaWarningPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ae5626ef70502687a859f323a809ed0b6>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaWarningPush](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ae5626ef70502687a859f323a809ed0b6) Callback
PragmaWarningPush is called when a #pragma warning(push) directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-Level (number) int Warning level.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| Level | (number) | int | Warning level. |
-Example:::
+Example:
- - Callback: PragmaWarningPush
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
- Level: 1
+```yaml
+- Callback: PragmaWarningPush
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+ Level: 1
+```
-`PragmaWarningPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac98d502af8811b8a6e7342d7cd2b3b95>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [PragmaWarningPop](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac98d502af8811b8a6e7342d7cd2b3b95) Callback
PragmaWarningPop is called when a #pragma warning(pop) directive is read.
Argument descriptions:
-============== ================================================== ============================== ==============================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-============== ================================================== ============================== ==============================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------- | ------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
-Example:::
+Example:
- - Callback: PragmaWarningPop
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+```yaml
+- Callback: PragmaWarningPop
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
+```
-`MacroExpands <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a9bc725209d3a071ea649144ab996d515>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [MacroExpands](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a9bc725209d3a071ea649144ab996d515) Callback
MacroExpands is called when ::HandleMacroExpandedIdentifier when a macro invocation is found.
Argument descriptions:
-============== ================================================== ============================== ======================================================================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ======================================================================================================
-MacroNameTok (token) const Token The macro name token.
-MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure.
-Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the expansion.
-Args [(name)|(number)|<(token name)>[, ...]] const MacroArgs The argument tokens. Names and numbers are literal, everything else is of the form '<' tokenName '>'.
-============== ================================================== ============================== ======================================================================================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | ---------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
+| MacroNameTok | (token) | const Token | The macro name token. |
+| MacroDirective | (MD_Define\|MD_Undefine\|MD_Visibility) | const MacroDirective | The kind of macro directive from the MacroDirective structure. |
+| Range | ["(file):(line):(col)", "(file):(line):(col)"] | SourceRange | The source range for the expansion. |
+| Args | \[(name)\|(number)\|\<(token name)>[, ...]\] | const MacroArgs | The argument tokens. Names and numbers are literal, everything else is of the form '\<' tokenName '>'. |
-Example:::
+Example:
- - Callback: MacroExpands
- MacroNameTok: X_IMPL
- MacroDirective: MD_Define
- Range: [(nonfile), (nonfile)]
- Args: [a <plus> y, b]
+```yaml
+- Callback: MacroExpands
+ MacroNameTok: X_IMPL
+ MacroDirective: MD_Define
+ Range: [(nonfile), (nonfile)]
+ Args: [a <plus> y, b]
+```
-`MacroDefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a8448fc9f96f22ad1b93ff393cffc5a76>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [MacroDefined](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a8448fc9f96f22ad1b93ff393cffc5a76) Callback
MacroDefined is called when a macro definition is seen.
Argument descriptions:
-============== ================================================== ============================== ==============================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================================================
-MacroNameTok (token) const Token The macro name token.
-MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure.
-============== ================================================== ============================== ==============================================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | --------------------------------------- | -------------------- | -------------------------------------------------------------- |
+| MacroNameTok | (token) | const Token | The macro name token. |
+| MacroDirective | (MD_Define\|MD_Undefine\|MD_Visibility) | const MacroDirective | The kind of macro directive from the MacroDirective structure. |
-Example:::
+Example:
- - Callback: MacroDefined
- MacroNameTok: X_IMPL
- MacroDirective: MD_Define
+```yaml
+- Callback: MacroDefined
+ MacroNameTok: X_IMPL
+ MacroDirective: MD_Define
+```
-`MacroUndefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#acb80fc6171a839db8e290945bf2c9d7a>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [MacroUndefined](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#acb80fc6171a839db8e290945bf2c9d7a) Callback
MacroUndefined is called when a macro #undef is seen.
Argument descriptions:
-============== ================================================== ============================== ==============================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================================================
-MacroNameTok (token) const Token The macro name token.
-MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure.
-============== ================================================== ============================== ==============================================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | --------------------------------------- | -------------------- | -------------------------------------------------------------- |
+| MacroNameTok | (token) | const Token | The macro name token. |
+| MacroDirective | (MD_Define\|MD_Undefine\|MD_Visibility) | const MacroDirective | The kind of macro directive from the MacroDirective structure. |
-Example:::
+Example:
- - Callback: MacroUndefined
- MacroNameTok: X_IMPL
- MacroDirective: MD_Define
+```yaml
+- Callback: MacroUndefined
+ MacroNameTok: X_IMPL
+ MacroDirective: MD_Define
+```
-`Defined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3cc2a644533d0e4088a13d2baf90db94>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [Defined](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3cc2a644533d0e4088a13d2baf90db94) Callback
Defined is called when the 'defined' operator is seen.
Argument descriptions:
-============== ================================================== ============================== ==============================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================================================
-MacroNameTok (token) const Token The macro name token.
-MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure.
-Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the directive.
-============== ================================================== ============================== ==============================================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | ---------------------------------------------- | -------------------- | -------------------------------------------------------------- |
+| MacroNameTok | (token) | const Token | The macro name token. |
+| MacroDirective | (MD_Define\|MD_Undefine\|MD_Visibility) | const MacroDirective | The kind of macro directive from the MacroDirective structure. |
+| Range | ["(file):(line):(col)", "(file):(line):(col)"] | SourceRange | The source range for the directive. |
-Example:::
+Example:
- - Callback: Defined
- MacroNameTok: MACRO
- MacroDirective: (null)
- Range: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:5", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:19"]
+```yaml
+- Callback: Defined
+ MacroNameTok: MACRO
+ MacroDirective: (null)
+ Range: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:5", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:19"]
+```
-`SourceRangeSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abdb4ebe11610f079ac33515965794b46>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [SourceRangeSkipped](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abdb4ebe11610f079ac33515965794b46) Callback
SourceRangeSkipped is called when a source range is skipped.
Argument descriptions:
-============== ================================================== ============================== =========================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== =========================
-Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range skipped.
-============== ================================================== ============================== =========================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | ---------------------------------------------- | -------------- | ------------------------- |
+| Range | ["(file):(line):(col)", "(file):(line):(col)"] | SourceRange | The source range skipped. |
-Example:::
+Example:
- - Callback: SourceRangeSkipped
- Range: [":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2", ":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:2"]
+```yaml
+- Callback: SourceRangeSkipped
+ Range: [":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2", ":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:2"]
+```
-`If <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a645edcb0d6becbc6f256f02fd1287778>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [If](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a645edcb0d6becbc6f256f02fd1287778) Callback
If is called when an #if is seen.
Argument descriptions:
-============== ================================================== ============================== ===================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ===================================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-ConditionRange ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the condition.
-ConditionValue (true|false) bool The condition value.
-============== ================================================== ============================== ===================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | ---------------------------------------------- | -------------- | ----------------------------------- |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| ConditionRange | ["(file):(line):(col)", "(file):(line):(col)"] | SourceRange | The source range for the condition. |
+| ConditionValue | (true\|false) | bool | The condition value. |
-Example:::
+Example:
- - Callback: If
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
- ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:1"]
- ConditionValue: false
+```yaml
+- Callback: If
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
+ ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:1"]
+ ConditionValue: false
+```
-`Elif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a180c9e106a28d60a6112e16b1bb8302a>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [Elif](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a180c9e106a28d60a6112e16b1bb8302a) Callback
Elif is called when an #elif is seen.
Argument descriptions:
-============== ================================================== ============================== ===================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ===================================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-ConditionRange ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the condition.
-ConditionValue (true|false) bool The condition value.
-IfLoc "(file):(line):(col)" SourceLocation The location of the directive.
-============== ================================================== ============================== ===================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | ---------------------------------------------- | -------------- | ----------------------------------- |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| ConditionRange | ["(file):(line):(col)", "(file):(line):(col)"] | SourceRange | The source range for the condition. |
+| ConditionValue | (true\|false) | bool | The condition value. |
+| IfLoc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
-Example:::
+Example:
- - Callback: Elif
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
- ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:11:1"]
- ConditionValue: false
- IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
+```yaml
+- Callback: Elif
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
+ ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:11:1"]
+ ConditionValue: false
+ IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
+```
-`Ifdef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0ce79575dda307784fd51a6dd4eec33d>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [Ifdef](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0ce79575dda307784fd51a6dd4eec33d) Callback
Ifdef is called when an #ifdef is seen.
Argument descriptions:
-============== ================================================== ============================== ==============================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================================================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-MacroNameTok (token) const Token The macro name token.
-MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure.
-============== ================================================== ============================== ==============================================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | --------------------------------------- | -------------------- | -------------------------------------------------------------- |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| MacroNameTok | (token) | const Token | The macro name token. |
+| MacroDirective | (MD_Define\|MD_Undefine\|MD_Visibility) | const MacroDirective | The kind of macro directive from the MacroDirective structure. |
-Example:::
+Example:
- - Callback: Ifdef
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"
- MacroNameTok: MACRO
- MacroDirective: MD_Define
+```yaml
+- Callback: Ifdef
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"
+ MacroNameTok: MACRO
+ MacroDirective: MD_Define
+```
-`Ifndef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a767af69f1cdcc4cd880fa2ebf77ad3ad>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [Ifndef](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a767af69f1cdcc4cd880fa2ebf77ad3ad) Callback
Ifndef is called when an #ifndef is seen.
Argument descriptions:
-============== ================================================== ============================== ==============================================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ==============================================================
-Loc "(file):(line):(col)" SourceLocation The location of the directive.
-MacroNameTok (token) const Token The macro name token.
-MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure.
-============== ================================================== ============================== ==============================================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| -------------- | --------------------------------------- | -------------------- | -------------------------------------------------------------- |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the directive. |
+| MacroNameTok | (token) | const Token | The macro name token. |
+| MacroDirective | (MD_Define\|MD_Undefine\|MD_Visibility) | const MacroDirective | The kind of macro directive from the MacroDirective structure. |
-Example:::
+Example:
- - Callback: Ifndef
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"
- MacroNameTok: MACRO
- MacroDirective: MD_Define
+```yaml
+- Callback: Ifndef
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"
+ MacroNameTok: MACRO
+ MacroDirective: MD_Define
+```
-`Else <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ad57f91b6d9c3cbcca326a2bfb49e0314>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [Else](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ad57f91b6d9c3cbcca326a2bfb49e0314) Callback
Else is called when an #else is seen.
Argument descriptions:
-============== ================================================== ============================== ===================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ===================================
-Loc "(file):(line):(col)" SourceLocation The location of the else directive.
-IfLoc "(file):(line):(col)" SourceLocation The location of the if directive.
-============== ================================================== ============================== ===================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------- | ----------------------------------- |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the else directive. |
+| IfLoc | "(file):(line):(col)" | SourceLocation | The location of the if directive. |
-Example:::
+Example:
- - Callback: Else
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
- IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
+```yaml
+- Callback: Else
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
+ IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
+```
-`Endif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afc62ca1401125f516d58b1629a2093ce>`_ Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### [Endif](https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afc62ca1401125f516d58b1629a2093ce) Callback
Endif is called when an #endif is seen.
Argument descriptions:
-============== ================================================== ============================== ====================================
-Argument Name Argument Value Syntax Clang C++ Type Description
-============== ================================================== ============================== ====================================
-Loc "(file):(line):(col)" SourceLocation The location of the endif directive.
-IfLoc "(file):(line):(col)" SourceLocation The location of the if directive.
-============== ================================================== ============================== ====================================
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |
+| ------------- | --------------------- | -------------- | ------------------------------------ |
+| Loc | "(file):(line):(col)" | SourceLocation | The location of the endif directive. |
+| IfLoc | "(file):(line):(col)" | SourceLocation | The location of the if directive. |
-Example:::
+Example:
- - Callback: Endif
- Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
- IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
+```yaml
+- Callback: Endif
+ Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
+ IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
+```
-Building pp-trace
-=================
+## Building pp-trace
To build from source:
-1. Read `Getting Started with the LLVM System`_ and `Clang Tools
- Documentation`_ for information on getting sources for LLVM, Clang, and
+1. Read [Getting Started with the LLVM System][getting started with the llvm system] and [Clang Tools
+ Documentation][clang tools documentation] for information on getting sources for LLVM, Clang, and
Clang Extra Tools.
-2. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give
+2. [Getting Started with the LLVM System][getting started with the llvm system] and [Building LLVM with CMake][building llvm with cmake] give
directions for how to build. With sources all checked out into the
right place the LLVM build will build Clang Extra Tools and their
dependencies automatically.
- * If using CMake, you can also use the ``pp-trace`` target to build
+ - If using CMake, you can also use the `pp-trace` target to build
just the pp-trace tool and its dependencies.
-.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
-.. _Building LLVM with CMake: https://llvm.org/docs/CMake.html
-.. _Clang Tools Documentation: https://clang.llvm.org/docs/ClangTools.html
+[building llvm with cmake]: https://llvm.org/docs/CMake.html
+[clang tools documentation]: https://clang.llvm.org/docs/ClangTools.html
+[getting started with the llvm system]: https://llvm.org/docs/GettingStarted.html
+
More information about the cfe-commits
mailing list