Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[rustdoc] Remove unneeded jinja comments #130706

Merged
merged 2 commits into from
Sep 27, 2024
Merged

[rustdoc] Remove unneeded jinja comments #130706

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6915039
Extend rustdoc template check to detect unneeded comments
GuillaumeGomez Sep 22, 2024
575df06
Remove unneeded jinja comments in templates
GuillaumeGomez Sep 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/librustdoc/html/templates/item_info.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{% if !items.is_empty() %}
<span class="item-info">
{% for item in items %}
{{item|safe}} {# #}
{{item|safe}}
{% endfor %}
</span>
{% endif %}
62 changes: 31 additions & 31 deletions src/librustdoc/html/templates/page.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}}" {#+ #}
Expand All @@ -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> {# #}
Expand All @@ -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> {# #}
2 changes: 1 addition & 1 deletion src/librustdoc/html/templates/print_item.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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() %}
Expand Down
10 changes: 5 additions & 5 deletions src/librustdoc/html/templates/short_item_info.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)) %}
&nbsp;<a href="{{url}}{{num}}">#{{num}}</a> {# #}
&nbsp;<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 %}
2 changes: 1 addition & 1 deletion src/librustdoc/html/templates/sidebar.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ <h3> {# #}
{% else %}
{{link.name}}
{% endmatch %}
</a> {# #}
</a>
{% if !link.children.is_empty() %}
<ul>
{% for child in link.children %}
Expand Down
2 changes: 1 addition & 1 deletion src/librustdoc/html/templates/source.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down
20 changes: 10 additions & 10 deletions src/librustdoc/html/templates/type_layout.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"> {# #}
Expand All @@ -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>`. #}
Expand All @@ -35,29 +35,29 @@ <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. #}
{% when Err(LayoutError::SizeOverflow(_)) %}
<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> {# #}
34 changes: 33 additions & 1 deletion src/tools/tidy/src/rustdoc_templates.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
Loading