rustdoc: add separate section for module items

Author: notriddle

src/librustdoc/html/render/context.rs

@@ -14,9 +14,12 @@ use rustc_span::edition::Edition;
 use rustc_span::{sym, FileName, Symbol};
 
 use super::print_item::{full_path, item_path, print_item};
-use super::sidebar::{print_sidebar, sidebar_module_like, Sidebar};
 use super::write_shared::write_shared;
-use super::{collect_spans_and_sources, scrape_examples_help, AllTypes, LinkFromSrc, StylePath};
+use super::{
+    collect_spans_and_sources, scrape_examples_help,
+    sidebar::{print_sidebar, sidebar_module_like, ModuleLike, Sidebar},
+    AllTypes, LinkFromSrc, StylePath,
+};
 use crate::clean::types::ExternalLocation;
 use crate::clean::utils::has_doc_flag;
 use crate::clean::{self, ExternalCrate};
@@ -617,7 +620,7 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
         let mut sidebar = Buffer::html();
 
         // all.html is not customizable, so a blank id map is fine
-        let blocks = sidebar_module_like(all.item_sections(), &mut IdMap::new());
+        let blocks = sidebar_module_like(all.item_sections(), &mut IdMap::new(), ModuleLike::Crate);
         let bar = Sidebar {
             title_prefix: "",
             title: "",

src/librustdoc/html/render/sidebar.rs

@@ -15,6 +15,18 @@ use crate::{
 
 use super::{item_ty_to_section, Context, ItemSection};
 
+#[derive(Clone, Copy)]
+pub(crate) enum ModuleLike {
+    Module,
+    Crate,
+}
+
+impl ModuleLike {
+    pub(crate) fn is_crate(self) -> bool {
+        matches!(self, ModuleLike::Crate)
+    }
+}
+
 #[derive(Template)]
 #[template(path = "sidebar.html")]
 pub(super) struct Sidebar<'a> {
@@ -530,14 +542,23 @@ fn sidebar_enum<'a>(
 pub(crate) fn sidebar_module_like(
     item_sections_in_use: FxHashSet<ItemSection>,
     ids: &mut IdMap,
+    module_like: ModuleLike,
 ) -> LinkBlock<'static> {
-    let item_sections = ItemSection::ALL
+    let item_sections: Vec<Link<'_>> = ItemSection::ALL
         .iter()
         .copied()
         .filter(|sec| item_sections_in_use.contains(sec))
         .map(|sec| Link::new(ids.derive(sec.id()), sec.name()))
         .collect();
-    LinkBlock::new(Link::empty(), "", item_sections)
+    let header = if let Some(first_section) = item_sections.get(0) {
+        Link::new(
+            first_section.href.to_owned(),
+            if module_like.is_crate() { "Crate Items" } else { "Module Items" },
+        )
+    } else {
+        Link::empty()
+    };
+    LinkBlock::new(header, "", item_sections)
 }
 
 fn sidebar_module(items: &[clean::Item], ids: &mut IdMap) -> LinkBlock<'static> {
@@ -561,7 +582,7 @@ fn sidebar_module(items: &[clean::Item], ids: &mut IdMap) -> LinkBlock<'static>
         .map(|it| item_ty_to_section(it.type_()))
         .collect();
 
-    sidebar_module_like(item_sections_in_use, ids)
+    sidebar_module_like(item_sections_in_use, ids, ModuleLike::Module)
 }
 
 fn sidebar_foreign_type<'a>(

src/librustdoc/html/templates/sidebar.html

@@ -17,21 +17,21 @@ <h2 class="location"> {# #}
                     {% if !block.heading.name.is_empty() %}
                         <h3> {# #}
                             <a href="#{{block.heading.href|safe}}">{{block.heading.name|wrapped|safe}}</a> {# #}
-                        </h3> {# #}
+                        </h3>
                     {% endif %}
                     {% if !block.links.is_empty() %}
                         <ul class="block{% if !block.class.is_empty() +%} {{+block.class}}{% endif %}">
                             {% for link in block.links %}
                                 <li> {# #}
                                     <a href="#{{link.href|safe}}">{{link.name}}</a> {# #}
                                     {% if !link.children.is_empty() %}
-                                        <ul> {# #}
+                                        <ul>
                                             {% for child in link.children %}
                                                 <li><a href="#{{child.href|safe}}">{{child.name}}</a></li>
                                             {% endfor %}
-                                        </ul> {# #}
+                                        </ul>
                                     {% endif %}
-                                </li> {# #}
+                                </li>
                             {% endfor %}
                         </ul>
                     {% endif %}
@@ -43,7 +43,7 @@ <h3> {# #}
     {% if !path.is_empty() %}
         <h2{% if parent_is_crate +%} class="in-crate"{% endif %}> {# #}
             <a href="{% if is_mod %}../{% endif %}index.html">In {{+ path|wrapped|safe}}</a> {# #}
-        </h2> {# #}
+        </h2>
     {% endif %}
     </div> {# #}
 </div>

tests/rustdoc/sidebar/top-toc-nil.rs

@@ -0,0 +1,7 @@
+#![crate_name = "foo"]
+
+//! This test case covers missing top TOC entries.
+
+// @has foo/index.html
+// User header
+// @!has - '//section[@id="TOC"]/ul[@class="block top-toc"]' 'Basic link and emphasis'