From 69150396bf145ab19488263f2a111ef48338dced Mon Sep 17 00:00:00 2001
From: Guillaume Gomez <guillaume.gomez@huawei.com>
Date: Sun, 22 Sep 2024 17:06:00 +0200
Subject: [PATCH 1/2] Extend rustdoc template check to detect unneeded comments
---
src/tools/tidy/src/rustdoc_templates.rs | 34 ++++++++++++++++++++++++-
1 file changed, 33 insertions(+), 1 deletion(-)
diff --git a/src/tools/tidy/src/rustdoc_templates.rs b/src/tools/tidy/src/rustdoc_templates.rs
index 6c8530e6366f6..2173dbf7e746a 100644
--- a/src/tools/tidy/src/rustdoc_templates.rs
+++ b/src/tools/tidy/src/rustdoc_templates.rs
@@ -20,7 +20,39 @@ pub fn check(librustdoc_path: &Path, bad: &mut bool) {
while let Some((pos, line)) = lines.next() {
let line = line.trim();
- if TAGS.iter().any(|(_, tag)| line.ends_with(tag)) {
+ if let Some(need_next_line_check) = TAGS.iter().find_map(|(tag, end_tag)| {
+ // We first check if the line ends with a jinja tag.
+ if !line.ends_with(end_tag) {
+ return None;
+ // Then we check if this a comment tag.
+ } else if *tag != "{#" {
+ return Some(false);
+ // And finally we check if the comment is empty (ie, only there to strip
+ // extra whitespace characters).
+ } else if let Some(start_pos) = line.rfind(tag) {
+ Some(line[start_pos + 2..].trim() == "#}")
+ } else {
+ Some(false)
+ }
+ }) {
+ // All good, the line is ending is a jinja tag. But maybe this tag is useless
+ // if the next line starts with a jinja tag as well!
+ //
+ // However, only (empty) comment jinja tags are concerned about it.
+ if need_next_line_check
+ && lines.peek().is_some_and(|(_, next_line)| {
+ let next_line = next_line.trim_start();
+ TAGS.iter().any(|(tag, _)| next_line.starts_with(tag))
+ })
+ {
+ // It seems like ending this line with a jinja tag is not needed after all.
+ tidy_error!(
+ bad,
+ "`{}` at line {}: unneeded `{{# #}}` tag at the end of the line",
+ path.path().display(),
+ pos + 1,
+ );
+ }
continue;
}
let Some(next_line) = lines.peek().map(|(_, next_line)| next_line.trim()) else {
From 575df06a8b48f567ed1c53edc61facfee6f42e9c Mon Sep 17 00:00:00 2001
From: Guillaume Gomez <guillaume.gomez@huawei.com>
Date: Sun, 22 Sep 2024 17:06:19 +0200
Subject: [PATCH 2/2] Remove unneeded jinja comments in templates
---
src/librustdoc/html/templates/item_info.html | 2 +-
src/librustdoc/html/templates/page.html | 62 +++++++++----------
src/librustdoc/html/templates/print_item.html | 2 +-
.../html/templates/short_item_info.html | 10 +--
src/librustdoc/html/templates/sidebar.html | 2 +-
src/librustdoc/html/templates/source.html | 2 +-
.../html/templates/type_layout.html | 20 +++---
7 files changed, 50 insertions(+), 50 deletions(-)
diff --git a/src/librustdoc/html/templates/item_info.html b/src/librustdoc/html/templates/item_info.html
index 9e65ae95e15d2..9fee268622e81 100644
--- a/src/librustdoc/html/templates/item_info.html
+++ b/src/librustdoc/html/templates/item_info.html
@@ -1,7 +1,7 @@
{% if !items.is_empty() %}
<span class="item-info">
{% for item in items %}
- {{item|safe}} {# #}
+ {{item|safe}}
{% endfor %}
</span>
{% endif %}
diff --git a/src/librustdoc/html/templates/page.html b/src/librustdoc/html/templates/page.html
index 65c4304e20207..a05d6ca831329 100644
--- a/src/librustdoc/html/templates/page.html
+++ b/src/librustdoc/html/templates/page.html
@@ -12,13 +12,13 @@
<link rel="stylesheet" {#+ #}
href="{{static_root_path|safe}}{{files.normalize_css}}"> {# #}
<link rel="stylesheet" {#+ #}
- href="{{static_root_path|safe}}{{files.rustdoc_css}}"> {# #}
+ href="{{static_root_path|safe}}{{files.rustdoc_css}}">
{% if !layout.default_settings.is_empty() %}
<script id="default-settings" {#+ #}
{%~ for (k, v) in layout.default_settings ~%}
data-{{k}}="{{v}}"
{% endfor %}
- ></script> {# #}
+ ></script>
{% endif %}
<meta name="rustdoc-vars" {#+ #}
data-root-path="{{page.root_path|safe}}" {#+ #}
@@ -31,36 +31,36 @@
data-search-js="{{files.search_js}}" {#+ #}
data-settings-js="{{files.settings_js}}" {#+ #}
> {# #}
- <script src="{{static_root_path|safe}}{{files.storage_js}}"></script> {# #}
+ <script src="{{static_root_path|safe}}{{files.storage_js}}"></script>
{% if page.css_class.contains("crate") %}
- <script defer src="{{page.root_path|safe}}crates{{page.resource_suffix}}.js"></script> {# #}
+ <script defer src="{{page.root_path|safe}}crates{{page.resource_suffix}}.js"></script>
{% else if page.css_class == "src" %}
<script defer src="{{static_root_path|safe}}{{files.src_script_js}}"></script> {# #}
- <script defer src="{{page.root_path|safe}}src-files{{page.resource_suffix}}.js"></script> {# #}
+ <script defer src="{{page.root_path|safe}}src-files{{page.resource_suffix}}.js"></script>
{% else if !page.css_class.contains("mod") %}
- <script defer src="sidebar-items{{page.resource_suffix}}.js"></script> {# #}
+ <script defer src="sidebar-items{{page.resource_suffix}}.js"></script>
{% else if !page.css_class.contains("sys") %}
- <script defer src="../sidebar-items{{page.resource_suffix}}.js"></script> {# #}
+ <script defer src="../sidebar-items{{page.resource_suffix}}.js"></script>
{% endif %}
- <script defer src="{{static_root_path|safe}}{{files.main_js}}"></script> {# #}
+ <script defer src="{{static_root_path|safe}}{{files.main_js}}"></script>
{% if layout.scrape_examples_extension %}
- <script defer src="{{static_root_path|safe}}{{files.scrape_examples_js}}"></script> {# #}
+ <script defer src="{{static_root_path|safe}}{{files.scrape_examples_js}}"></script>
{% endif %}
<noscript> {# #}
<link rel="stylesheet" {#+ #}
href="{{static_root_path|safe}}{{files.noscript_css}}"> {# #}
- </noscript> {# #}
+ </noscript>
{% if layout.css_file_extension.is_some() %}
<link rel="stylesheet" {#+ #}
- href="{{page.root_path|safe}}theme{{page.resource_suffix}}.css"> {# #}
+ href="{{page.root_path|safe}}theme{{page.resource_suffix}}.css">
{% endif %}
{% if !layout.favicon.is_empty() %}
- <link rel="icon" href="{{layout.favicon}}"> {# #}
+ <link rel="icon" href="{{layout.favicon}}">
{% else %}
<link rel="alternate icon" type="image/png" {#+ #}
href="{{static_root_path|safe}}{{files.rust_favicon_png_32}}"> {# #}
<link rel="icon" type="image/svg+xml" {#+ #}
- href="{{static_root_path|safe}}{{files.rust_favicon_svg}}"> {# #}
+ href="{{static_root_path|safe}}{{files.rust_favicon_svg}}">
{% endif %}
{{ layout.external_html.in_header|safe }}
</head> {# #}
@@ -69,60 +69,60 @@
<div class="warning"> {# #}
This old browser is unsupported and will most likely display funky things. {# #}
</div> {# #}
- <![endif]--> {# #}
+ <![endif]-->
{{ layout.external_html.before_content|safe }}
{% if page.css_class != "src" %}
<nav class="mobile-topbar"> {# #}
- <button class="sidebar-menu-toggle" title="show sidebar"></button> {# #}
+ <button class="sidebar-menu-toggle" title="show sidebar"></button>
{% if !layout.logo.is_empty() || page.rust_logo %}
- <a class="logo-container" href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html"> {# #}
+ <a class="logo-container" href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html">
{% if page.rust_logo %}
- <img class="rust-logo" src="{{static_root_path|safe}}{{files.rust_logo_svg}}" alt=""> {# #}
+ <img class="rust-logo" src="{{static_root_path|safe}}{{files.rust_logo_svg}}" alt="">
{% else if !layout.logo.is_empty() %}
- <img src="{{layout.logo}}" alt=""> {# #}
+ <img src="{{layout.logo}}" alt="">
{% endif %}
- </a> {# #}
+ </a>
{% endif %}
</nav>
{% endif %}
- <nav class="sidebar"> {# #}
+ <nav class="sidebar">
{% if page.css_class != "src" %}
<div class="sidebar-crate">
{% if !layout.logo.is_empty() || page.rust_logo %}
- <a class="logo-container" href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html"> {# #}
+ <a class="logo-container" href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html">
{% if page.rust_logo %}
- <img class="rust-logo" src="{{static_root_path|safe}}{{files.rust_logo_svg}}" alt="logo"> {# #}
+ <img class="rust-logo" src="{{static_root_path|safe}}{{files.rust_logo_svg}}" alt="logo">
{% else if !layout.logo.is_empty() %}
- <img src="{{layout.logo}}" alt="logo"> {# #}
+ <img src="{{layout.logo}}" alt="logo">
{% endif %}
- </a> {# #}
+ </a>
{% endif %}
<h2> {# #}
- <a href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html">{{display_krate|wrapped|safe}}</a> {# #}
+ <a href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html">{{display_krate|wrapped|safe}}</a>
{% if !display_krate_version_number.is_empty() %}
<span class="version">{{+ display_krate_version_number}}</span>
{% endif %}
</h2> {# #}
- </div> {# #}
+ </div>
{% if !display_krate_version_extra.is_empty() %}
- <div class="version">{{+ display_krate_version_extra}}</div> {# #}
+ <div class="version">{{+ display_krate_version_extra}}</div>
{% endif %}
{% else %}
<div class="src-sidebar-title"> {# #}
<h2>Files</h2> {# #}
- </div> {# #}
+ </div>
{% endif %}
{{ sidebar|safe }}
</nav> {# #}
<div class="sidebar-resizer"></div> {# #}
- <main> {# #}
+ <main>
{% if page.css_class != "src" %}<div class="width-limiter">{% endif %}
{# defined in storage.js to avoid duplicating complex UI across every page #}
{# and because the search form only works if JS is enabled anyway #}
<rustdoc-search></rustdoc-search> {# #}
- <section id="main-content" class="content">{{ content|safe }}</section> {# #}
+ <section id="main-content" class="content">{{ content|safe }}</section>
{% if page.css_class != "src" %}</div>{% endif %}
- </main> {# #}
+ </main>
{{ layout.external_html.after_content|safe }}
</body> {# #}
</html> {# #}
diff --git a/src/librustdoc/html/templates/print_item.html b/src/librustdoc/html/templates/print_item.html
index 32ded1fbe424f..f60720b67c64c 100644
--- a/src/librustdoc/html/templates/print_item.html
+++ b/src/librustdoc/html/templates/print_item.html
@@ -1,4 +1,4 @@
-<div class="main-heading"> {# #}
+<div class="main-heading">
{% if !path_components.is_empty() %}
<span class="rustdoc-breadcrumbs">
{% for (i, component) in path_components.iter().enumerate() %}
diff --git a/src/librustdoc/html/templates/short_item_info.html b/src/librustdoc/html/templates/short_item_info.html
index 75d155e91c203..e76b98541cf61 100644
--- a/src/librustdoc/html/templates/short_item_info.html
+++ b/src/librustdoc/html/templates/short_item_info.html
@@ -3,21 +3,21 @@
<div class="stab deprecated"> {# #}
<span class="emoji">๐</span> {# #}
<span>{{message|safe}}</span> {# #}
- </div> {# #}
+ </div>
{% when Self::Unstable with { feature, tracking } %}
<div class="stab unstable"> {# #}
<span class="emoji">๐ฌ</span> {# #}
<span> {# #}
This is a nightly-only experimental API. ({# #}
- <code>{{feature}}</code> {# #}
+ <code>{{feature}}</code>
{% match tracking %}
{% when Some with ((url, num)) %}
- <a href="{{url}}{{num}}">#{{num}}</a> {# #}
+ <a href="{{url}}{{num}}">#{{num}}</a>
{% when None %}
{% endmatch %}
) {# #}
</span> {# #}
- </div> {# #}
+ </div>
{% when Self::Portability with { message } %}
- <div class="stab portability">{{message|safe}}</div> {# #}
+ <div class="stab portability">{{message|safe}}</div>
{% endmatch %}
diff --git a/src/librustdoc/html/templates/sidebar.html b/src/librustdoc/html/templates/sidebar.html
index fccf65cbefcf9..7f852b489fa24 100644
--- a/src/librustdoc/html/templates/sidebar.html
+++ b/src/librustdoc/html/templates/sidebar.html
@@ -30,7 +30,7 @@ <h3> {# #}
{% else %}
{{link.name}}
{% endmatch %}
- </a> {# #}
+ </a>
{% if !link.children.is_empty() %}
<ul>
{% for child in link.children %}
diff --git a/src/librustdoc/html/templates/source.html b/src/librustdoc/html/templates/source.html
index 9daa0cf8ff688..ea530087e6f09 100644
--- a/src/librustdoc/html/templates/source.html
+++ b/src/librustdoc/html/templates/source.html
@@ -9,7 +9,7 @@ <h1> {# #}
</div>
{% else %}
{% endmatch %}
-<div class="example-wrap"> {# #}
+<div class="example-wrap">
{# https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag#data-nosnippet-attr
Do not show "1 2 3 4 5 ..." in web search results. #}
<div data-nosnippet><pre class="src-line-numbers">
diff --git a/src/librustdoc/html/templates/type_layout.html b/src/librustdoc/html/templates/type_layout.html
index e0516bb42fe40..aee96fb8c417e 100644
--- a/src/librustdoc/html/templates/type_layout.html
+++ b/src/librustdoc/html/templates/type_layout.html
@@ -1,7 +1,7 @@
<h2 id="layout" class="section-header"> {# #}
Layout<a href="#layout" class="anchor">ยง</a> {# #}
</h2> {# #}
-<div class="docblock"> {# #}
+<div class="docblock">
{% match type_layout_size %}
{% when Ok(type_layout_size) %}
<div class="warning"> {# #}
@@ -14,19 +14,19 @@ <h2 id="layout" class="section-header"> {# #}
chapter for details on type layout guarantees. {# #}
</p> {# #}
</div> {# #}
- <p><strong>Size:</strong> {{+ type_layout_size|safe }}</p> {# #}
+ <p><strong>Size:</strong> {{+ type_layout_size|safe }}</p>
{% if !variants.is_empty() %}
<p> {# #}
<strong>Size for each variant:</strong> {# #}
</p> {# #}
- <ul> {# #}
+ <ul>
{% for (name, layout_size) in variants %}
<li> {# #}
<code>{{ name }}</code>: {#+ #}
{{ layout_size|safe }}
- </li> {# #}
+ </li>
{% endfor %}
- </ul> {# #}
+ </ul>
{% endif %}
{# This kind of layout error can occur with valid code, e.g. if you try to
get the layout of a generic type such as `Vec<T>`. #}
@@ -35,7 +35,7 @@ <h2 id="layout" class="section-header"> {# #}
<strong>Note:</strong> Unable to compute type layout, {#+ #}
possibly due to this type having generic parameters. {#+ #}
Layout can only be computed for concrete, fully-instantiated types. {# #}
- </p> {# #}
+ </p>
{# This kind of error probably can't happen with valid code, but we don't
want to panic and prevent the docs from building, so we just let the
user know that we couldn't compute the layout. #}
@@ -43,21 +43,21 @@ <h2 id="layout" class="section-header"> {# #}
<p> {# #}
<strong>Note:</strong> Encountered an error during type layout; {#+ #}
the type was too big. {# #}
- </p> {# #}
+ </p>
{% when Err(LayoutError::ReferencesError(_)) %}
<p> {# #}
<strong>Note:</strong> Encountered an error during type layout; {#+ #}
the type references errors. {# #}
- </p> {# #}
+ </p>
{% when Err(LayoutError::NormalizationFailure(_, _)) %}
<p> {# #}
<strong>Note:</strong> Encountered an error during type layout; {#+ #}
the type failed to be normalized. {# #}
- </p> {# #}
+ </p>
{% when Err(LayoutError::Cycle(_)) %}
<p> {# #}
<strong>Note:</strong> Encountered an error during type layout; {#+ #}
the type's layout depended on the type's layout itself. {# #}
- </p> {# #}
+ </p>
{% endmatch %}
</div> {# #}