1use std::cmp::Ordering;
2use std::fmt::{self, Display, Write as _};
3use std::iter;
4
5use askama::Template;
6use rustc_abi::VariantIdx;
7use rustc_ast::join_path_syms;
8use rustc_data_structures::fx::{FxHashMap, FxIndexSet};
9use rustc_hir as hir;
10use rustc_hir::def::CtorKind;
11use rustc_hir::def_id::DefId;
12use rustc_index::IndexVec;
13use rustc_middle::ty::{self, TyCtxt};
14use rustc_span::hygiene::MacroKind;
15use rustc_span::symbol::{Symbol, sym};
16use tracing::{debug, info};
17
18use super::type_layout::document_type_layout;
19use super::{
20 AssocItemLink, AssocItemRender, Context, ImplRenderingParameters, RenderMode,
21 collect_paths_for_type, document, ensure_trailing_slash, get_filtered_impls_for_reference,
22 item_ty_to_section, notable_traits_button, notable_traits_json, render_all_impls,
23 render_assoc_item, render_assoc_items, render_attributes_in_code, render_impl,
24 render_repr_attribute_in_code, render_rightside, render_stability_since_raw,
25 render_stability_since_raw_with_extra, write_section_heading,
26};
27use crate::clean;
28use crate::config::ModuleSorting;
29use crate::display::{Joined as _, MaybeDisplay as _};
30use crate::formats::Impl;
31use crate::formats::item_type::ItemType;
32use crate::html::escape::{Escape, EscapeBodyTextWithWbr};
33use crate::html::format::{
34 Ending, PrintWithSpace, print_abi_with_space, print_constness_with_space, print_where_clause,
35 visibility_print_with_space,
36};
37use crate::html::markdown::{HeadingOffset, MarkdownSummaryLine};
38use crate::html::render::sidebar::filters;
39use crate::html::render::{document_full, document_item_info};
40use crate::html::url_parts_builder::UrlPartsBuilder;
41
42macro_rules! item_template {
61 (
62 $(#[$meta:meta])*
63 struct $name:ident<'a, 'cx> {
64 cx: &'a Context<'cx>,
65 it: &'a clean::Item,
66 $($field_name:ident: $field_ty:ty),*,
67 },
68 methods = [$($methods:tt),* $(,)?]
69 ) => {
70 #[derive(Template)]
71 $(#[$meta])*
72 struct $name<'a, 'cx> {
73 cx: &'a Context<'cx>,
74 it: &'a clean::Item,
75 $($field_name: $field_ty),*
76 }
77
78 impl<'a, 'cx: 'a> ItemTemplate<'a, 'cx> for $name<'a, 'cx> {
79 fn item_and_cx(&self) -> (&'a clean::Item, &'a Context<'cx>) {
80 (&self.it, &self.cx)
81 }
82 }
83
84 impl<'a, 'cx: 'a> $name<'a, 'cx> {
85 item_template_methods!($($methods)*);
86 }
87 };
88}
89
90macro_rules! item_template_methods {
94 () => {};
95 (document $($rest:tt)*) => {
96 fn document(&self) -> impl fmt::Display {
97 let (item, cx) = self.item_and_cx();
98 document(cx, item, None, HeadingOffset::H2)
99 }
100 item_template_methods!($($rest)*);
101 };
102 (document_type_layout $($rest:tt)*) => {
103 fn document_type_layout(&self) -> impl fmt::Display {
104 let (item, cx) = self.item_and_cx();
105 let def_id = item.item_id.expect_def_id();
106 document_type_layout(cx, def_id)
107 }
108 item_template_methods!($($rest)*);
109 };
110 (render_assoc_items $($rest:tt)*) => {
111 fn render_assoc_items(&self) -> impl fmt::Display {
112 let (item, cx) = self.item_and_cx();
113 let def_id = item.item_id.expect_def_id();
114 render_assoc_items(cx, item, def_id, AssocItemRender::All)
115 }
116 item_template_methods!($($rest)*);
117 };
118 ($method:ident $($rest:tt)*) => {
119 compile_error!(concat!("unknown method: ", stringify!($method)));
120 };
121 ($token:tt $($rest:tt)*) => {
122 compile_error!(concat!("unexpected token: ", stringify!($token)));
123 };
124}
125
126const ITEM_TABLE_OPEN: &str = "<dl class=\"item-table\">";
127const REEXPORTS_TABLE_OPEN: &str = "<dl class=\"item-table reexports\">";
128const ITEM_TABLE_CLOSE: &str = "</dl>";
129
130struct PathComponent {
132 path: String,
133 name: Symbol,
134}
135
136#[derive(Template)]
137#[template(path = "print_item.html")]
138struct ItemVars<'a> {
139 typ: &'a str,
140 name: &'a str,
141 item_type: &'a str,
142 path_components: Vec<PathComponent>,
143 stability_since_raw: &'a str,
144 src_href: Option<&'a str>,
145}
146
147pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item) -> impl fmt::Display {
148 debug_assert!(!item.is_stripped());
149
150 fmt::from_fn(|buf| {
151 let typ = match item.kind {
152 clean::ModuleItem(_) => {
153 if item.is_crate() {
154 "Crate "
155 } else {
156 "Module "
157 }
158 }
159 clean::FunctionItem(..) | clean::ForeignFunctionItem(..) => "Function ",
160 clean::TraitItem(..) => "Trait ",
161 clean::StructItem(..) => "Struct ",
162 clean::UnionItem(..) => "Union ",
163 clean::EnumItem(..) => "Enum ",
164 clean::TypeAliasItem(..) => "Type Alias ",
165 clean::MacroItem(..) => "Macro ",
166 clean::ProcMacroItem(ref mac) => match mac.kind {
167 MacroKind::Bang => "Macro ",
168 MacroKind::Attr => "Attribute Macro ",
169 MacroKind::Derive => "Derive Macro ",
170 },
171 clean::PrimitiveItem(..) => "Primitive Type ",
172 clean::StaticItem(..) | clean::ForeignStaticItem(..) => "Static ",
173 clean::ConstantItem(..) => "Constant ",
174 clean::ForeignTypeItem => "Foreign Type ",
175 clean::KeywordItem => "Keyword ",
176 clean::AttributeItem => "Attribute ",
177 clean::TraitAliasItem(..) => "Trait Alias ",
178 _ => {
179 unreachable!();
181 }
182 };
183 let stability_since_raw =
184 render_stability_since_raw(item.stable_since(cx.tcx()), item.const_stability(cx.tcx()))
185 .maybe_display()
186 .to_string();
187
188 let src_href =
195 if cx.info.include_sources && !item.is_primitive() { cx.src_href(item) } else { None };
196
197 let path_components = if item.is_fake_item() {
198 vec![]
199 } else {
200 let cur = &cx.current;
201 let amt = if item.is_mod() { cur.len() - 1 } else { cur.len() };
202 cur.iter()
203 .enumerate()
204 .take(amt)
205 .map(|(i, component)| PathComponent {
206 path: "../".repeat(cur.len() - i - 1),
207 name: *component,
208 })
209 .collect()
210 };
211
212 let item_vars = ItemVars {
213 typ,
214 name: item.name.as_ref().unwrap().as_str(),
215 item_type: &item.type_().to_string(),
216 path_components,
217 stability_since_raw: &stability_since_raw,
218 src_href: src_href.as_deref(),
219 };
220
221 item_vars.render_into(buf).unwrap();
222
223 match &item.kind {
224 clean::ModuleItem(m) => {
225 write!(buf, "{}", item_module(cx, item, &m.items))
226 }
227 clean::FunctionItem(f) | clean::ForeignFunctionItem(f, _) => {
228 write!(buf, "{}", item_function(cx, item, f))
229 }
230 clean::TraitItem(t) => write!(buf, "{}", item_trait(cx, item, t)),
231 clean::StructItem(s) => {
232 write!(buf, "{}", item_struct(cx, item, s))
233 }
234 clean::UnionItem(s) => write!(buf, "{}", item_union(cx, item, s)),
235 clean::EnumItem(e) => write!(buf, "{}", item_enum(cx, item, e)),
236 clean::TypeAliasItem(t) => {
237 write!(buf, "{}", item_type_alias(cx, item, t))
238 }
239 clean::MacroItem(m) => write!(buf, "{}", item_macro(cx, item, m)),
240 clean::ProcMacroItem(m) => {
241 write!(buf, "{}", item_proc_macro(cx, item, m))
242 }
243 clean::PrimitiveItem(_) => write!(buf, "{}", item_primitive(cx, item)),
244 clean::StaticItem(i) => {
245 write!(buf, "{}", item_static(cx, item, i, None))
246 }
247 clean::ForeignStaticItem(i, safety) => {
248 write!(buf, "{}", item_static(cx, item, i, Some(*safety)))
249 }
250 clean::ConstantItem(ci) => {
251 write!(buf, "{}", item_constant(cx, item, &ci.generics, &ci.type_, &ci.kind))
252 }
253 clean::ForeignTypeItem => {
254 write!(buf, "{}", item_foreign_type(cx, item))
255 }
256 clean::KeywordItem | clean::AttributeItem => {
257 write!(buf, "{}", item_keyword_or_attribute(cx, item))
258 }
259 clean::TraitAliasItem(ta) => {
260 write!(buf, "{}", item_trait_alias(cx, item, ta))
261 }
262 _ => {
263 unreachable!();
265 }
266 }?;
267
268 let mut types_with_notable_traits = cx.types_with_notable_traits.borrow_mut();
270 if !types_with_notable_traits.is_empty() {
271 write!(
272 buf,
273 r#"<script type="text/json" id="notable-traits-data">{}</script>"#,
274 notable_traits_json(types_with_notable_traits.iter(), cx),
275 )?;
276 types_with_notable_traits.clear();
277 }
278 Ok(())
279 })
280}
281
282fn should_hide_fields(n_fields: usize) -> bool {
284 n_fields > 12
285}
286
287fn toggle_open(mut w: impl fmt::Write, text: impl Display) {
288 write!(
289 w,
290 "<details class=\"toggle type-contents-toggle\">\
291 <summary class=\"hideme\">\
292 <span>Show {text}</span>\
293 </summary>",
294 )
295 .unwrap();
296}
297
298fn toggle_close(mut w: impl fmt::Write) {
299 w.write_str("</details>").unwrap();
300}
301
302trait ItemTemplate<'a, 'cx: 'a>: askama::Template + Display {
303 fn item_and_cx(&self) -> (&'a clean::Item, &'a Context<'cx>);
304}
305
306fn item_module(cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) -> impl fmt::Display {
307 fmt::from_fn(|w| {
308 write!(w, "{}", document(cx, item, None, HeadingOffset::H2))?;
309
310 let mut not_stripped_items =
311 items.iter().filter(|i| !i.is_stripped()).enumerate().collect::<Vec<_>>();
312
313 fn reorder(ty: ItemType) -> u8 {
315 match ty {
316 ItemType::ExternCrate => 0,
317 ItemType::Import => 1,
318 ItemType::Primitive => 2,
319 ItemType::Module => 3,
320 ItemType::Macro => 4,
321 ItemType::Struct => 5,
322 ItemType::Enum => 6,
323 ItemType::Constant => 7,
324 ItemType::Static => 8,
325 ItemType::Trait => 9,
326 ItemType::Function => 10,
327 ItemType::TypeAlias => 12,
328 ItemType::Union => 13,
329 _ => 14 + ty as u8,
330 }
331 }
332
333 fn cmp(i1: &clean::Item, i2: &clean::Item, tcx: TyCtxt<'_>) -> Ordering {
334 let rty1 = reorder(i1.type_());
335 let rty2 = reorder(i2.type_());
336 if rty1 != rty2 {
337 return rty1.cmp(&rty2);
338 }
339 let is_stable1 =
340 i1.stability(tcx).as_ref().map(|s| s.level.is_stable()).unwrap_or(true);
341 let is_stable2 =
342 i2.stability(tcx).as_ref().map(|s| s.level.is_stable()).unwrap_or(true);
343 if is_stable1 != is_stable2 {
344 return is_stable2.cmp(&is_stable1);
347 }
348 match (i1.name, i2.name) {
349 (Some(name1), Some(name2)) => compare_names(name1.as_str(), name2.as_str()),
350 (Some(_), None) => Ordering::Greater,
351 (None, Some(_)) => Ordering::Less,
352 (None, None) => Ordering::Equal,
353 }
354 }
355
356 let tcx = cx.tcx();
357
358 match cx.shared.module_sorting {
359 ModuleSorting::Alphabetical => {
360 not_stripped_items.sort_by(|(_, i1), (_, i2)| cmp(i1, i2, tcx));
361 }
362 ModuleSorting::DeclarationOrder => {}
363 }
364 not_stripped_items.dedup_by_key(|(idx, i)| {
384 (
385 i.item_id,
386 if i.name.is_some() { Some(full_path(cx, i)) } else { None },
387 i.type_(),
388 if i.is_import() { *idx } else { 0 },
389 )
390 });
391
392 debug!("{not_stripped_items:?}");
393 let mut last_section = None;
394
395 for (_, myitem) in ¬_stripped_items {
396 let my_section = item_ty_to_section(myitem.type_());
397 if Some(my_section) != last_section {
398 if last_section.is_some() {
399 w.write_str(ITEM_TABLE_CLOSE)?;
400 }
401 last_section = Some(my_section);
402 let section_id = my_section.id();
403 let tag =
404 if section_id == "reexports" { REEXPORTS_TABLE_OPEN } else { ITEM_TABLE_OPEN };
405 write!(
406 w,
407 "{}",
408 write_section_heading(my_section.name(), &cx.derive_id(section_id), None, tag)
409 )?;
410 }
411
412 match myitem.kind {
413 clean::ExternCrateItem { ref src } => {
414 use crate::html::format::print_anchor;
415
416 match *src {
417 Some(src) => {
418 write!(
419 w,
420 "<dt><code>{}extern crate {} as {};",
421 visibility_print_with_space(myitem, cx),
422 print_anchor(myitem.item_id.expect_def_id(), src, cx),
423 EscapeBodyTextWithWbr(myitem.name.unwrap().as_str())
424 )?;
425 }
426 None => {
427 write!(
428 w,
429 "<dt><code>{}extern crate {};",
430 visibility_print_with_space(myitem, cx),
431 print_anchor(
432 myitem.item_id.expect_def_id(),
433 myitem.name.unwrap(),
434 cx
435 )
436 )?;
437 }
438 }
439 w.write_str("</code></dt>")?;
440 }
441
442 clean::ImportItem(ref import) => {
443 let stab_tags = import.source.did.map_or_else(String::new, |import_def_id| {
444 print_extra_info_tags(tcx, myitem, item, Some(import_def_id)).to_string()
445 });
446
447 let id = match import.kind {
448 clean::ImportKind::Simple(s) => {
449 format!(" id=\"{}\"", cx.derive_id(format!("reexport.{s}")))
450 }
451 clean::ImportKind::Glob => String::new(),
452 };
453 write!(
454 w,
455 "<dt{id}>\
456 <code>"
457 )?;
458 render_attributes_in_code(w, myitem, "", cx);
459 write!(
460 w,
461 "{vis}{imp}</code>{stab_tags}\
462 </dt>",
463 vis = visibility_print_with_space(myitem, cx),
464 imp = import.print(cx)
465 )?;
466 }
467
468 _ => {
469 if myitem.name.is_none() {
470 continue;
471 }
472
473 let unsafety_flag = match myitem.kind {
474 clean::FunctionItem(_) | clean::ForeignFunctionItem(..)
475 if myitem.fn_header(tcx).unwrap().safety
476 == hir::HeaderSafety::Normal(hir::Safety::Unsafe) =>
477 {
478 "<sup title=\"unsafe function\">âš </sup>"
479 }
480 clean::ForeignStaticItem(_, hir::Safety::Unsafe) => {
481 "<sup title=\"unsafe static\">âš </sup>"
482 }
483 _ => "",
484 };
485
486 let visibility_and_hidden = match myitem.visibility(tcx) {
487 Some(ty::Visibility::Restricted(_)) => {
488 if myitem.is_doc_hidden() {
489 "<span title=\"Restricted Visibility\"> 🔒</span><span title=\"Hidden item\">👻</span> "
491 } else {
492 "<span title=\"Restricted Visibility\"> 🔒</span> "
493 }
494 }
495 _ if myitem.is_doc_hidden() => {
496 "<span title=\"Hidden item\"> 👻</span> "
497 }
498 _ => "",
499 };
500
501 let docs =
502 MarkdownSummaryLine(&myitem.doc_value(), &myitem.links(cx)).into_string();
503 let (docs_before, docs_after) =
504 if docs.is_empty() { ("", "") } else { ("<dd>", "</dd>") };
505 write!(
506 w,
507 "<dt>\
508 <a class=\"{class}\" href=\"{href}\" title=\"{title1} {title2}\">\
509 {name}\
510 </a>\
511 {visibility_and_hidden}\
512 {unsafety_flag}\
513 {stab_tags}\
514 </dt>\
515 {docs_before}{docs}{docs_after}",
516 name = EscapeBodyTextWithWbr(myitem.name.unwrap().as_str()),
517 visibility_and_hidden = visibility_and_hidden,
518 stab_tags = print_extra_info_tags(tcx, myitem, item, None),
519 class = myitem.type_(),
520 unsafety_flag = unsafety_flag,
521 href = print_item_path(myitem.type_(), myitem.name.unwrap().as_str()),
522 title1 = myitem.type_(),
523 title2 = full_path(cx, myitem),
524 )?;
525 }
526 }
527 }
528
529 if last_section.is_some() {
530 w.write_str(ITEM_TABLE_CLOSE)?;
531 }
532 Ok(())
533 })
534}
535
536fn print_extra_info_tags(
539 tcx: TyCtxt<'_>,
540 item: &clean::Item,
541 parent: &clean::Item,
542 import_def_id: Option<DefId>,
543) -> impl Display {
544 fmt::from_fn(move |f| {
545 fn tag_html(class: &str, title: &str, contents: &str) -> impl Display {
546 fmt::from_fn(move |f| {
547 write!(
548 f,
549 r#"<wbr><span class="stab {class}" title="{title}">{contents}</span>"#,
550 title = Escape(title),
551 )
552 })
553 }
554
555 let deprecation = import_def_id
557 .map_or_else(|| item.deprecation(tcx), |import_did| tcx.lookup_deprecation(import_did));
558 if let Some(depr) = deprecation {
559 let message = if depr.is_in_effect() { "Deprecated" } else { "Deprecation planned" };
560 write!(f, "{}", tag_html("deprecated", "", message))?;
561 }
562
563 let stability = import_def_id
566 .map_or_else(|| item.stability(tcx), |import_did| tcx.lookup_stability(import_did));
567 if stability.is_some_and(|s| s.is_unstable() && s.feature != sym::rustc_private) {
568 write!(f, "{}", tag_html("unstable", "", "Experimental"))?;
569 }
570
571 let cfg = match (&item.cfg, parent.cfg.as_ref()) {
572 (Some(cfg), Some(parent_cfg)) => cfg.simplify_with(parent_cfg),
573 (cfg, _) => cfg.as_deref().cloned(),
574 };
575
576 debug!(
577 "Portability name={name:?} {cfg:?} - {parent_cfg:?} = {cfg:?}",
578 name = item.name,
579 cfg = item.cfg,
580 parent_cfg = parent.cfg
581 );
582 if let Some(ref cfg) = cfg {
583 write!(
584 f,
585 "{}",
586 tag_html("portability", &cfg.render_long_plain(), &cfg.render_short_html())
587 )
588 } else {
589 Ok(())
590 }
591 })
592}
593
594fn item_function(cx: &Context<'_>, it: &clean::Item, f: &clean::Function) -> impl fmt::Display {
595 fmt::from_fn(|w| {
596 let tcx = cx.tcx();
597 let header = it.fn_header(tcx).expect("printing a function which isn't a function");
598 debug!(
599 "item_function/const: {:?} {:?} {:?} {:?}",
600 it.name,
601 &header.constness,
602 it.stable_since(tcx),
603 it.const_stability(tcx),
604 );
605 let constness = print_constness_with_space(
606 &header.constness,
607 it.stable_since(tcx),
608 it.const_stability(tcx),
609 );
610 let safety = header.safety.print_with_space();
611 let abi = print_abi_with_space(header.abi).to_string();
612 let asyncness = header.asyncness.print_with_space();
613 let visibility = visibility_print_with_space(it, cx).to_string();
614 let name = it.name.unwrap();
615
616 let generics_len = format!("{:#}", f.generics.print(cx)).len();
617 let header_len = "fn ".len()
618 + visibility.len()
619 + constness.len()
620 + asyncness.len()
621 + safety.len()
622 + abi.len()
623 + name.as_str().len()
624 + generics_len;
625
626 let notable_traits = notable_traits_button(&f.decl.output, cx).maybe_display();
627
628 wrap_item(w, |w| {
629 render_attributes_in_code(w, it, "", cx);
630 write!(
631 w,
632 "{vis}{constness}{asyncness}{safety}{abi}fn \
633 {name}{generics}{decl}{notable_traits}{where_clause}",
634 vis = visibility,
635 constness = constness,
636 asyncness = asyncness,
637 safety = safety,
638 abi = abi,
639 name = name,
640 generics = f.generics.print(cx),
641 where_clause =
642 print_where_clause(&f.generics, cx, 0, Ending::Newline).maybe_display(),
643 decl = f.decl.full_print(header_len, 0, cx),
644 )
645 })?;
646 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))
647 })
648}
649
650fn item_trait(cx: &Context<'_>, it: &clean::Item, t: &clean::Trait) -> impl fmt::Display {
651 fmt::from_fn(|w| {
652 let tcx = cx.tcx();
653 let bounds = print_bounds(&t.bounds, false, cx);
654 let required_types =
655 t.items.iter().filter(|m| m.is_required_associated_type()).collect::<Vec<_>>();
656 let provided_types = t.items.iter().filter(|m| m.is_associated_type()).collect::<Vec<_>>();
657 let required_consts =
658 t.items.iter().filter(|m| m.is_required_associated_const()).collect::<Vec<_>>();
659 let provided_consts =
660 t.items.iter().filter(|m| m.is_associated_const()).collect::<Vec<_>>();
661 let required_methods = t.items.iter().filter(|m| m.is_ty_method()).collect::<Vec<_>>();
662 let provided_methods = t.items.iter().filter(|m| m.is_method()).collect::<Vec<_>>();
663 let count_types = required_types.len() + provided_types.len();
664 let count_consts = required_consts.len() + provided_consts.len();
665 let count_methods = required_methods.len() + provided_methods.len();
666 let must_implement_one_of_functions = &tcx.trait_def(t.def_id).must_implement_one_of;
667
668 wrap_item(w, |mut w| {
670 render_attributes_in_code(&mut w, it, "", cx);
671 write!(
672 w,
673 "{vis}{safety}{is_auto}trait {name}{generics}{bounds}",
674 vis = visibility_print_with_space(it, cx),
675 safety = t.safety(tcx).print_with_space(),
676 is_auto = if t.is_auto(tcx) { "auto " } else { "" },
677 name = it.name.unwrap(),
678 generics = t.generics.print(cx),
679 )?;
680
681 if !t.generics.where_predicates.is_empty() {
682 write!(
683 w,
684 "{}",
685 print_where_clause(&t.generics, cx, 0, Ending::Newline).maybe_display()
686 )?;
687 } else {
688 w.write_char(' ')?;
689 }
690
691 if t.items.is_empty() {
692 w.write_str("{ }")
693 } else {
694 w.write_str("{\n")?;
696 let mut toggle = false;
697
698 if should_hide_fields(count_types) {
700 toggle = true;
701 toggle_open(
702 &mut w,
703 format_args!(
704 "{} associated items",
705 count_types + count_consts + count_methods
706 ),
707 );
708 }
709 for types in [&required_types, &provided_types] {
710 for t in types {
711 writeln!(
712 w,
713 "{};",
714 render_assoc_item(
715 t,
716 AssocItemLink::Anchor(None),
717 ItemType::Trait,
718 cx,
719 RenderMode::Normal,
720 )
721 )?;
722 }
723 }
724 if !toggle && should_hide_fields(count_types + count_consts) {
729 toggle = true;
730 toggle_open(
731 &mut w,
732 format_args!(
733 "{count_consts} associated constant{plural_const} and \
734 {count_methods} method{plural_method}",
735 plural_const = pluralize(count_consts),
736 plural_method = pluralize(count_methods),
737 ),
738 );
739 }
740 if count_types != 0 && (count_consts != 0 || count_methods != 0) {
741 w.write_str("\n")?;
742 }
743 for consts in [&required_consts, &provided_consts] {
744 for c in consts {
745 writeln!(
746 w,
747 "{};",
748 render_assoc_item(
749 c,
750 AssocItemLink::Anchor(None),
751 ItemType::Trait,
752 cx,
753 RenderMode::Normal,
754 )
755 )?;
756 }
757 }
758 if !toggle && should_hide_fields(count_methods) {
759 toggle = true;
760 toggle_open(&mut w, format_args!("{count_methods} methods"));
761 }
762 if count_consts != 0 && count_methods != 0 {
763 w.write_str("\n")?;
764 }
765
766 if !required_methods.is_empty() {
767 writeln!(w, " // Required method{}", pluralize(required_methods.len()))?;
768 }
769 for (pos, m) in required_methods.iter().enumerate() {
770 writeln!(
771 w,
772 "{};",
773 render_assoc_item(
774 m,
775 AssocItemLink::Anchor(None),
776 ItemType::Trait,
777 cx,
778 RenderMode::Normal,
779 )
780 )?;
781
782 if pos < required_methods.len() - 1 {
783 w.write_str("<span class=\"item-spacer\"></span>")?;
784 }
785 }
786 if !required_methods.is_empty() && !provided_methods.is_empty() {
787 w.write_str("\n")?;
788 }
789
790 if !provided_methods.is_empty() {
791 writeln!(w, " // Provided method{}", pluralize(provided_methods.len()))?;
792 }
793 for (pos, m) in provided_methods.iter().enumerate() {
794 writeln!(
795 w,
796 "{} {{ ... }}",
797 render_assoc_item(
798 m,
799 AssocItemLink::Anchor(None),
800 ItemType::Trait,
801 cx,
802 RenderMode::Normal,
803 )
804 )?;
805
806 if pos < provided_methods.len() - 1 {
807 w.write_str("<span class=\"item-spacer\"></span>")?;
808 }
809 }
810 if toggle {
811 toggle_close(&mut w);
812 }
813 w.write_str("}")
814 }
815 })?;
816
817 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))?;
819
820 fn trait_item(cx: &Context<'_>, m: &clean::Item, t: &clean::Item) -> impl fmt::Display {
821 fmt::from_fn(|w| {
822 let name = m.name.unwrap();
823 info!("Documenting {name} on {ty_name:?}", ty_name = t.name);
824 let item_type = m.type_();
825 let id = cx.derive_id(format!("{item_type}.{name}"));
826
827 let content = document_full(m, cx, HeadingOffset::H5).to_string();
828
829 let toggled = !content.is_empty();
830 if toggled {
831 let method_toggle_class =
832 if item_type.is_method() { " method-toggle" } else { "" };
833 write!(w, "<details class=\"toggle{method_toggle_class}\" open><summary>")?;
834 }
835 write!(
836 w,
837 "<section id=\"{id}\" class=\"method\">\
838 {}\
839 <h4 class=\"code-header\">{}</h4></section>",
840 render_rightside(cx, m, RenderMode::Normal),
841 render_assoc_item(
842 m,
843 AssocItemLink::Anchor(Some(&id)),
844 ItemType::Impl,
845 cx,
846 RenderMode::Normal,
847 )
848 )?;
849 document_item_info(cx, m, Some(t)).render_into(w).unwrap();
850 if toggled {
851 write!(w, "</summary>{content}</details>")?;
852 }
853 Ok(())
854 })
855 }
856
857 if !required_consts.is_empty() {
858 write!(
859 w,
860 "{}",
861 write_section_heading(
862 "Required Associated Constants",
863 "required-associated-consts",
864 None,
865 "<div class=\"methods\">",
866 )
867 )?;
868 for t in required_consts {
869 write!(w, "{}", trait_item(cx, t, it))?;
870 }
871 w.write_str("</div>")?;
872 }
873 if !provided_consts.is_empty() {
874 write!(
875 w,
876 "{}",
877 write_section_heading(
878 "Provided Associated Constants",
879 "provided-associated-consts",
880 None,
881 "<div class=\"methods\">",
882 )
883 )?;
884 for t in provided_consts {
885 write!(w, "{}", trait_item(cx, t, it))?;
886 }
887 w.write_str("</div>")?;
888 }
889
890 if !required_types.is_empty() {
891 write!(
892 w,
893 "{}",
894 write_section_heading(
895 "Required Associated Types",
896 "required-associated-types",
897 None,
898 "<div class=\"methods\">",
899 )
900 )?;
901 for t in required_types {
902 write!(w, "{}", trait_item(cx, t, it))?;
903 }
904 w.write_str("</div>")?;
905 }
906 if !provided_types.is_empty() {
907 write!(
908 w,
909 "{}",
910 write_section_heading(
911 "Provided Associated Types",
912 "provided-associated-types",
913 None,
914 "<div class=\"methods\">",
915 )
916 )?;
917 for t in provided_types {
918 write!(w, "{}", trait_item(cx, t, it))?;
919 }
920 w.write_str("</div>")?;
921 }
922
923 if !required_methods.is_empty() || must_implement_one_of_functions.is_some() {
925 write!(
926 w,
927 "{}",
928 write_section_heading(
929 "Required Methods",
930 "required-methods",
931 None,
932 "<div class=\"methods\">",
933 )
934 )?;
935
936 if let Some(list) = must_implement_one_of_functions.as_deref() {
937 write!(
938 w,
939 "<div class=\"stab must_implement\">At least one of the `{}` methods is required.</div>",
940 fmt::from_fn(|f| list.iter().joined("`, `", f)),
941 )?;
942 }
943
944 for m in required_methods {
945 write!(w, "{}", trait_item(cx, m, it))?;
946 }
947 w.write_str("</div>")?;
948 }
949 if !provided_methods.is_empty() {
950 write!(
951 w,
952 "{}",
953 write_section_heading(
954 "Provided Methods",
955 "provided-methods",
956 None,
957 "<div class=\"methods\">",
958 )
959 )?;
960 for m in provided_methods {
961 write!(w, "{}", trait_item(cx, m, it))?;
962 }
963 w.write_str("</div>")?;
964 }
965
966 write!(
968 w,
969 "{}",
970 render_assoc_items(cx, it, it.item_id.expect_def_id(), AssocItemRender::All)
971 )?;
972
973 let mut extern_crates = FxIndexSet::default();
974
975 if !t.is_dyn_compatible(cx.tcx()) {
976 write!(
977 w,
978 "{}",
979 write_section_heading(
980 "Dyn Compatibility",
981 "dyn-compatibility",
982 None,
983 format!(
984 "<div class=\"dyn-compatibility-info\"><p>This trait is <b>not</b> \
985 <a href=\"{base}/reference/items/traits.html#dyn-compatibility\">dyn compatible</a>.</p>\
986 <p><i>In older versions of Rust, dyn compatibility was called \"object safety\", \
987 so this trait is not object safe.</i></p></div>",
988 base = crate::clean::utils::DOC_RUST_LANG_ORG_VERSION
989 ),
990 ),
991 )?;
992 }
993
994 if let Some(implementors) = cx.shared.cache.implementors.get(&it.item_id.expect_def_id()) {
995 let mut implementor_dups: FxHashMap<Symbol, (DefId, bool)> = FxHashMap::default();
998 for implementor in implementors {
999 if let Some(did) =
1000 implementor.inner_impl().for_.without_borrowed_ref().def_id(&cx.shared.cache)
1001 && !did.is_local()
1002 {
1003 extern_crates.insert(did.krate);
1004 }
1005 match implementor.inner_impl().for_.without_borrowed_ref() {
1006 clean::Type::Path { path } if !path.is_assoc_ty() => {
1007 let did = path.def_id();
1008 let &mut (prev_did, ref mut has_duplicates) =
1009 implementor_dups.entry(path.last()).or_insert((did, false));
1010 if prev_did != did {
1011 *has_duplicates = true;
1012 }
1013 }
1014 _ => {}
1015 }
1016 }
1017
1018 let (local, mut foreign) =
1019 implementors.iter().partition::<Vec<_>, _>(|i| i.is_on_local_type(cx));
1020
1021 let (mut synthetic, mut concrete): (Vec<&&Impl>, Vec<&&Impl>) =
1022 local.iter().partition(|i| i.inner_impl().kind.is_auto());
1023
1024 synthetic.sort_by_cached_key(|i| ImplString::new(i, cx));
1025 concrete.sort_by_cached_key(|i| ImplString::new(i, cx));
1026 foreign.sort_by_cached_key(|i| ImplString::new(i, cx));
1027
1028 if !foreign.is_empty() {
1029 write!(
1030 w,
1031 "{}",
1032 write_section_heading(
1033 "Implementations on Foreign Types",
1034 "foreign-impls",
1035 None,
1036 ""
1037 )
1038 )?;
1039
1040 for implementor in foreign {
1041 let provided_methods = implementor.inner_impl().provided_trait_methods(tcx);
1042 let assoc_link =
1043 AssocItemLink::GotoSource(implementor.impl_item.item_id, &provided_methods);
1044 write!(
1045 w,
1046 "{}",
1047 render_impl(
1048 cx,
1049 implementor,
1050 it,
1051 assoc_link,
1052 RenderMode::Normal,
1053 None,
1054 &[],
1055 ImplRenderingParameters {
1056 show_def_docs: false,
1057 show_default_items: false,
1058 show_non_assoc_items: true,
1059 toggle_open_by_default: false,
1060 },
1061 )
1062 )?;
1063 }
1064 }
1065
1066 write!(
1067 w,
1068 "{}",
1069 write_section_heading(
1070 "Implementors",
1071 "implementors",
1072 None,
1073 "<div id=\"implementors-list\">",
1074 )
1075 )?;
1076 for implementor in concrete {
1077 write!(w, "{}", render_implementor(cx, implementor, it, &implementor_dups, &[]))?;
1078 }
1079 w.write_str("</div>")?;
1080
1081 if t.is_auto(tcx) {
1082 write!(
1083 w,
1084 "{}",
1085 write_section_heading(
1086 "Auto implementors",
1087 "synthetic-implementors",
1088 None,
1089 "<div id=\"synthetic-implementors-list\">",
1090 )
1091 )?;
1092 for implementor in synthetic {
1093 write!(
1094 w,
1095 "{}",
1096 render_implementor(
1097 cx,
1098 implementor,
1099 it,
1100 &implementor_dups,
1101 &collect_paths_for_type(
1102 &implementor.inner_impl().for_,
1103 &cx.shared.cache,
1104 ),
1105 )
1106 )?;
1107 }
1108 w.write_str("</div>")?;
1109 }
1110 } else {
1111 write!(
1114 w,
1115 "{}",
1116 write_section_heading(
1117 "Implementors",
1118 "implementors",
1119 None,
1120 "<div id=\"implementors-list\"></div>",
1121 )
1122 )?;
1123
1124 if t.is_auto(tcx) {
1125 write!(
1126 w,
1127 "{}",
1128 write_section_heading(
1129 "Auto implementors",
1130 "synthetic-implementors",
1131 None,
1132 "<div id=\"synthetic-implementors-list\"></div>",
1133 )
1134 )?;
1135 }
1136 }
1137
1138 let mut js_src_path: UrlPartsBuilder =
1210 iter::repeat_n("..", cx.current.len()).chain(iter::once("trait.impl")).collect();
1211 if let Some(did) = it.item_id.as_def_id()
1212 && let get_extern = { || cx.shared.cache.external_paths.get(&did).map(|s| &s.0) }
1213 && let Some(fqp) = cx.shared.cache.exact_paths.get(&did).or_else(get_extern)
1214 {
1215 js_src_path.extend(fqp[..fqp.len() - 1].iter().copied());
1216 js_src_path.push_fmt(format_args!("{}.{}.js", it.type_(), fqp.last().unwrap()));
1217 } else {
1218 js_src_path.extend(cx.current.iter().copied());
1219 js_src_path.push_fmt(format_args!("{}.{}.js", it.type_(), it.name.unwrap()));
1220 }
1221 let extern_crates = fmt::from_fn(|f| {
1222 if !extern_crates.is_empty() {
1223 f.write_str(" data-ignore-extern-crates=\"")?;
1224 extern_crates.iter().map(|&cnum| tcx.crate_name(cnum)).joined(",", f)?;
1225 f.write_str("\"")?;
1226 }
1227 Ok(())
1228 });
1229 write!(
1230 w,
1231 "<script src=\"{src}\"{extern_crates} async></script>",
1232 src = js_src_path.finish()
1233 )
1234 })
1235}
1236
1237fn item_trait_alias(
1238 cx: &Context<'_>,
1239 it: &clean::Item,
1240 t: &clean::TraitAlias,
1241) -> impl fmt::Display {
1242 fmt::from_fn(|w| {
1243 wrap_item(w, |w| {
1244 render_attributes_in_code(w, it, "", cx);
1245 write!(
1246 w,
1247 "trait {name}{generics} = {bounds}{where_clause};",
1248 name = it.name.unwrap(),
1249 generics = t.generics.print(cx),
1250 bounds = print_bounds(&t.bounds, true, cx),
1251 where_clause =
1252 print_where_clause(&t.generics, cx, 0, Ending::NoNewline).maybe_display(),
1253 )
1254 })?;
1255
1256 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))?;
1257 write!(
1262 w,
1263 "{}",
1264 render_assoc_items(cx, it, it.item_id.expect_def_id(), AssocItemRender::All)
1265 )
1266 })
1267}
1268
1269fn item_type_alias(cx: &Context<'_>, it: &clean::Item, t: &clean::TypeAlias) -> impl fmt::Display {
1270 fmt::from_fn(|w| {
1271 wrap_item(w, |w| {
1272 render_attributes_in_code(w, it, "", cx);
1273 write!(
1274 w,
1275 "{vis}type {name}{generics}{where_clause} = {type_};",
1276 vis = visibility_print_with_space(it, cx),
1277 name = it.name.unwrap(),
1278 generics = t.generics.print(cx),
1279 where_clause =
1280 print_where_clause(&t.generics, cx, 0, Ending::Newline).maybe_display(),
1281 type_ = t.type_.print(cx),
1282 )
1283 })?;
1284
1285 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))?;
1286
1287 if let Some(inner_type) = &t.inner_type {
1288 write!(w, "{}", write_section_heading("Aliased Type", "aliased-type", None, ""),)?;
1289
1290 match inner_type {
1291 clean::TypeAliasInnerType::Enum { variants, is_non_exhaustive } => {
1292 let ty = cx.tcx().type_of(it.def_id().unwrap()).instantiate_identity();
1293 let enum_def_id = ty.ty_adt_def().unwrap().did();
1294
1295 DisplayEnum {
1296 variants,
1297 generics: &t.generics,
1298 is_non_exhaustive: *is_non_exhaustive,
1299 def_id: enum_def_id,
1300 }
1301 .render_into(cx, it, true, w)?;
1302 }
1303 clean::TypeAliasInnerType::Union { fields } => {
1304 let ty = cx.tcx().type_of(it.def_id().unwrap()).instantiate_identity();
1305 let union_def_id = ty.ty_adt_def().unwrap().did();
1306
1307 ItemUnion {
1308 cx,
1309 it,
1310 fields,
1311 generics: &t.generics,
1312 is_type_alias: true,
1313 def_id: union_def_id,
1314 }
1315 .render_into(w)?;
1316 }
1317 clean::TypeAliasInnerType::Struct { ctor_kind, fields } => {
1318 let ty = cx.tcx().type_of(it.def_id().unwrap()).instantiate_identity();
1319 let struct_def_id = ty.ty_adt_def().unwrap().did();
1320
1321 DisplayStruct {
1322 ctor_kind: *ctor_kind,
1323 generics: &t.generics,
1324 fields,
1325 def_id: struct_def_id,
1326 }
1327 .render_into(cx, it, true, w)?;
1328 }
1329 }
1330 } else {
1331 let def_id = it.item_id.expect_def_id();
1332 write!(
1337 w,
1338 "{}{}",
1339 render_assoc_items(cx, it, def_id, AssocItemRender::All),
1340 document_type_layout(cx, def_id)
1341 )?;
1342 }
1343
1344 let cache = &cx.shared.cache;
1417 if let Some(target_did) = t.type_.def_id(cache)
1418 && let get_extern = { || cache.external_paths.get(&target_did) }
1419 && let Some(&(ref target_fqp, target_type)) =
1420 cache.paths.get(&target_did).or_else(get_extern)
1421 && target_type.is_adt() && let Some(self_did) = it.item_id.as_def_id()
1423 && let get_local = { || cache.paths.get(&self_did).map(|(p, _)| p) }
1424 && let Some(self_fqp) = cache.exact_paths.get(&self_did).or_else(get_local)
1425 {
1426 let mut js_src_path: UrlPartsBuilder =
1427 iter::repeat_n("..", cx.current.len()).chain(iter::once("type.impl")).collect();
1428 js_src_path.extend(target_fqp[..target_fqp.len() - 1].iter().copied());
1429 js_src_path.push_fmt(format_args!("{target_type}.{}.js", target_fqp.last().unwrap()));
1430 let self_path = join_path_syms(self_fqp);
1431 write!(
1432 w,
1433 "<script src=\"{src}\" data-self-path=\"{self_path}\" async></script>",
1434 src = js_src_path.finish(),
1435 )?;
1436 }
1437 Ok(())
1438 })
1439}
1440
1441item_template!(
1442 #[template(path = "item_union.html")]
1443 struct ItemUnion<'a, 'cx> {
1444 cx: &'a Context<'cx>,
1445 it: &'a clean::Item,
1446 fields: &'a [clean::Item],
1447 generics: &'a clean::Generics,
1448 is_type_alias: bool,
1449 def_id: DefId,
1450 },
1451 methods = [document, document_type_layout, render_assoc_items]
1452);
1453
1454impl<'a, 'cx: 'a> ItemUnion<'a, 'cx> {
1455 fn render_union(&self) -> impl Display {
1456 render_union(
1457 self.it,
1458 Some(self.generics),
1459 self.fields,
1460 self.def_id,
1461 self.is_type_alias,
1462 self.cx,
1463 )
1464 }
1465
1466 fn print_field_attrs(&self, field: &'a clean::Item) -> impl Display {
1467 fmt::from_fn(move |w| {
1468 render_attributes_in_code(w, field, "", self.cx);
1469 Ok(())
1470 })
1471 }
1472
1473 fn document_field(&self, field: &'a clean::Item) -> impl Display {
1474 document(self.cx, field, Some(self.it), HeadingOffset::H3)
1475 }
1476
1477 fn stability_field(&self, field: &clean::Item) -> Option<String> {
1478 field.stability_class(self.cx.tcx())
1479 }
1480
1481 fn print_ty(&self, ty: &'a clean::Type) -> impl Display {
1482 ty.print(self.cx)
1483 }
1484
1485 fn fields_iter(&self) -> impl Iterator<Item = (&'a clean::Item, &'a clean::Type)> {
1492 self.fields.iter().filter_map(|f| match f.kind {
1493 clean::StructFieldItem(ref ty) => Some((f, ty)),
1494 _ => None,
1495 })
1496 }
1497}
1498
1499fn item_union(cx: &Context<'_>, it: &clean::Item, s: &clean::Union) -> impl fmt::Display {
1500 fmt::from_fn(|w| {
1501 ItemUnion {
1502 cx,
1503 it,
1504 fields: &s.fields,
1505 generics: &s.generics,
1506 is_type_alias: false,
1507 def_id: it.def_id().unwrap(),
1508 }
1509 .render_into(w)?;
1510 Ok(())
1511 })
1512}
1513
1514fn print_tuple_struct_fields(cx: &Context<'_>, s: &[clean::Item]) -> impl Display {
1515 fmt::from_fn(|f| {
1516 if !s.is_empty()
1517 && s.iter().all(|field| {
1518 matches!(field.kind, clean::StrippedItem(box clean::StructFieldItem(..)))
1519 })
1520 {
1521 return f.write_str("<span class=\"comment\">/* private fields */</span>");
1522 }
1523
1524 s.iter()
1525 .map(|ty| {
1526 fmt::from_fn(|f| match ty.kind {
1527 clean::StrippedItem(box clean::StructFieldItem(_)) => f.write_str("_"),
1528 clean::StructFieldItem(ref ty) => write!(f, "{}", ty.print(cx)),
1529 _ => unreachable!(),
1530 })
1531 })
1532 .joined(", ", f)
1533 })
1534}
1535
1536struct DisplayEnum<'clean> {
1537 variants: &'clean IndexVec<VariantIdx, clean::Item>,
1538 generics: &'clean clean::Generics,
1539 is_non_exhaustive: bool,
1540 def_id: DefId,
1541}
1542
1543impl<'clean> DisplayEnum<'clean> {
1544 fn render_into<W: fmt::Write>(
1545 self,
1546 cx: &Context<'_>,
1547 it: &clean::Item,
1548 is_type_alias: bool,
1549 w: &mut W,
1550 ) -> fmt::Result {
1551 let non_stripped_variant_count = self.variants.iter().filter(|i| !i.is_stripped()).count();
1552 let variants_len = self.variants.len();
1553 let has_stripped_entries = variants_len != non_stripped_variant_count;
1554
1555 wrap_item(w, |w| {
1556 if is_type_alias {
1557 render_repr_attribute_in_code(w, cx, self.def_id);
1559 } else {
1560 render_attributes_in_code(w, it, "", cx);
1561 }
1562 write!(
1563 w,
1564 "{}enum {}{}{}",
1565 visibility_print_with_space(it, cx),
1566 it.name.unwrap(),
1567 self.generics.print(cx),
1568 render_enum_fields(
1569 cx,
1570 Some(self.generics),
1571 self.variants,
1572 non_stripped_variant_count,
1573 has_stripped_entries,
1574 self.is_non_exhaustive,
1575 self.def_id,
1576 ),
1577 )
1578 })?;
1579
1580 let def_id = it.item_id.expect_def_id();
1581 let layout_def_id = if is_type_alias {
1582 self.def_id
1583 } else {
1584 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))?;
1585 def_id
1588 };
1589
1590 if non_stripped_variant_count != 0 {
1591 write!(w, "{}", item_variants(cx, it, self.variants, self.def_id))?;
1592 }
1593 write!(
1594 w,
1595 "{}{}",
1596 render_assoc_items(cx, it, def_id, AssocItemRender::All),
1597 document_type_layout(cx, layout_def_id)
1598 )
1599 }
1600}
1601
1602fn item_enum(cx: &Context<'_>, it: &clean::Item, e: &clean::Enum) -> impl fmt::Display {
1603 fmt::from_fn(|w| {
1604 DisplayEnum {
1605 variants: &e.variants,
1606 generics: &e.generics,
1607 is_non_exhaustive: it.is_non_exhaustive(),
1608 def_id: it.def_id().unwrap(),
1609 }
1610 .render_into(cx, it, false, w)
1611 })
1612}
1613
1614fn should_show_enum_discriminant(
1618 cx: &Context<'_>,
1619 enum_def_id: DefId,
1620 variants: &IndexVec<VariantIdx, clean::Item>,
1621) -> bool {
1622 let mut has_variants_with_value = false;
1623 for variant in variants {
1624 if let clean::VariantItem(ref var) = variant.kind
1625 && matches!(var.kind, clean::VariantKind::CLike)
1626 {
1627 has_variants_with_value |= var.discriminant.is_some();
1628 } else {
1629 return false;
1630 }
1631 }
1632 if has_variants_with_value {
1633 return true;
1634 }
1635 let repr = cx.tcx().adt_def(enum_def_id).repr();
1636 repr.c() || repr.int.is_some()
1637}
1638
1639fn display_c_like_variant(
1640 cx: &Context<'_>,
1641 item: &clean::Item,
1642 variant: &clean::Variant,
1643 index: VariantIdx,
1644 should_show_enum_discriminant: bool,
1645 enum_def_id: DefId,
1646) -> impl fmt::Display {
1647 fmt::from_fn(move |w| {
1648 let name = item.name.unwrap();
1649 if let Some(ref value) = variant.discriminant {
1650 write!(w, "{} = {}", name.as_str(), value.value(cx.tcx(), true))?;
1651 } else if should_show_enum_discriminant {
1652 let adt_def = cx.tcx().adt_def(enum_def_id);
1653 let discr = adt_def.discriminant_for_variant(cx.tcx(), index);
1654 write!(w, "{} = {}", name.as_str(), discr)?;
1657 } else {
1658 write!(w, "{name}")?;
1659 }
1660 Ok(())
1661 })
1662}
1663
1664fn render_enum_fields(
1665 cx: &Context<'_>,
1666 g: Option<&clean::Generics>,
1667 variants: &IndexVec<VariantIdx, clean::Item>,
1668 count_variants: usize,
1669 has_stripped_entries: bool,
1670 is_non_exhaustive: bool,
1671 enum_def_id: DefId,
1672) -> impl fmt::Display {
1673 fmt::from_fn(move |w| {
1674 let should_show_enum_discriminant =
1675 should_show_enum_discriminant(cx, enum_def_id, variants);
1676 if let Some(generics) = g
1677 && let Some(where_clause) = print_where_clause(generics, cx, 0, Ending::Newline)
1678 {
1679 write!(w, "{where_clause}")?;
1680 } else {
1681 w.write_char(' ')?;
1683 }
1684
1685 let variants_stripped = has_stripped_entries;
1686 if count_variants == 0 && !variants_stripped {
1687 w.write_str("{}")
1688 } else {
1689 w.write_str("{\n")?;
1690 let toggle = should_hide_fields(count_variants);
1691 if toggle {
1692 toggle_open(&mut *w, format_args!("{count_variants} variants"));
1693 }
1694 const TAB: &str = " ";
1695 for (index, v) in variants.iter_enumerated() {
1696 if v.is_stripped() {
1697 continue;
1698 }
1699 render_attributes_in_code(w, v, TAB, cx);
1700 w.write_str(TAB)?;
1701 match v.kind {
1702 clean::VariantItem(ref var) => match var.kind {
1703 clean::VariantKind::CLike => {
1704 write!(
1705 w,
1706 "{}",
1707 display_c_like_variant(
1708 cx,
1709 v,
1710 var,
1711 index,
1712 should_show_enum_discriminant,
1713 enum_def_id,
1714 )
1715 )?;
1716 }
1717 clean::VariantKind::Tuple(ref s) => {
1718 write!(w, "{}({})", v.name.unwrap(), print_tuple_struct_fields(cx, s))?;
1719 }
1720 clean::VariantKind::Struct(ref s) => {
1721 write!(
1722 w,
1723 "{}",
1724 render_struct(v, None, None, &s.fields, TAB, false, cx)
1725 )?;
1726 }
1727 },
1728 _ => unreachable!(),
1729 }
1730 w.write_str(",\n")?;
1731 }
1732
1733 if variants_stripped && !is_non_exhaustive {
1734 w.write_str(" <span class=\"comment\">// some variants omitted</span>\n")?;
1735 }
1736 if toggle {
1737 toggle_close(&mut *w);
1738 }
1739 w.write_str("}")
1740 }
1741 })
1742}
1743
1744fn item_variants(
1745 cx: &Context<'_>,
1746 it: &clean::Item,
1747 variants: &IndexVec<VariantIdx, clean::Item>,
1748 enum_def_id: DefId,
1749) -> impl fmt::Display {
1750 fmt::from_fn(move |w| {
1751 let tcx = cx.tcx();
1752 write!(
1753 w,
1754 "{}",
1755 write_section_heading(
1756 &format!("Variants{}", document_non_exhaustive_header(it)),
1757 "variants",
1758 Some("variants"),
1759 format!("{}<div class=\"variants\">", document_non_exhaustive(it)),
1760 ),
1761 )?;
1762
1763 let should_show_enum_discriminant =
1764 should_show_enum_discriminant(cx, enum_def_id, variants);
1765 for (index, variant) in variants.iter_enumerated() {
1766 if variant.is_stripped() {
1767 continue;
1768 }
1769 let id = cx.derive_id(format!("{}.{}", ItemType::Variant, variant.name.unwrap()));
1770 write!(
1771 w,
1772 "<section id=\"{id}\" class=\"variant\">\
1773 <a href=\"#{id}\" class=\"anchor\">§</a>\
1774 {}\
1775 <h3 class=\"code-header\">",
1776 render_stability_since_raw_with_extra(
1777 variant.stable_since(tcx),
1778 variant.const_stability(tcx),
1779 " rightside",
1780 )
1781 .maybe_display()
1782 )?;
1783 render_attributes_in_code(w, variant, "", cx);
1784 if let clean::VariantItem(ref var) = variant.kind
1785 && let clean::VariantKind::CLike = var.kind
1786 {
1787 write!(
1788 w,
1789 "{}",
1790 display_c_like_variant(
1791 cx,
1792 variant,
1793 var,
1794 index,
1795 should_show_enum_discriminant,
1796 enum_def_id,
1797 )
1798 )?;
1799 } else {
1800 w.write_str(variant.name.unwrap().as_str())?;
1801 }
1802
1803 let clean::VariantItem(variant_data) = &variant.kind else { unreachable!() };
1804
1805 if let clean::VariantKind::Tuple(ref s) = variant_data.kind {
1806 write!(w, "({})", print_tuple_struct_fields(cx, s))?;
1807 }
1808 w.write_str("</h3></section>")?;
1809
1810 write!(w, "{}", document(cx, variant, Some(it), HeadingOffset::H4))?;
1811
1812 let heading_and_fields = match &variant_data.kind {
1813 clean::VariantKind::Struct(s) => {
1814 if s.fields.iter().any(|f| !f.is_doc_hidden()) {
1816 Some(("Fields", &s.fields))
1817 } else {
1818 None
1819 }
1820 }
1821 clean::VariantKind::Tuple(fields) => {
1822 if fields.iter().any(|f| !f.doc_value().is_empty()) {
1825 Some(("Tuple Fields", fields))
1826 } else {
1827 None
1828 }
1829 }
1830 clean::VariantKind::CLike => None,
1831 };
1832
1833 if let Some((heading, fields)) = heading_and_fields {
1834 let variant_id =
1835 cx.derive_id(format!("{}.{}.fields", ItemType::Variant, variant.name.unwrap()));
1836 write!(
1837 w,
1838 "<div class=\"sub-variant\" id=\"{variant_id}\">\
1839 <h4>{heading}</h4>\
1840 {}",
1841 document_non_exhaustive(variant)
1842 )?;
1843 for field in fields {
1844 match field.kind {
1845 clean::StrippedItem(box clean::StructFieldItem(_)) => {}
1846 clean::StructFieldItem(ref ty) => {
1847 let id = cx.derive_id(format!(
1848 "variant.{}.field.{}",
1849 variant.name.unwrap(),
1850 field.name.unwrap()
1851 ));
1852 write!(
1853 w,
1854 "<div class=\"sub-variant-field\">\
1855 <span id=\"{id}\" class=\"section-header\">\
1856 <a href=\"#{id}\" class=\"anchor field\">§</a>\
1857 <code>"
1858 )?;
1859 render_attributes_in_code(w, field, "", cx);
1860 write!(
1861 w,
1862 "{f}: {t}</code>\
1863 </span>\
1864 {doc}\
1865 </div>",
1866 f = field.name.unwrap(),
1867 t = ty.print(cx),
1868 doc = document(cx, field, Some(variant), HeadingOffset::H5),
1869 )?;
1870 }
1871 _ => unreachable!(),
1872 }
1873 }
1874 w.write_str("</div>")?;
1875 }
1876 }
1877 w.write_str("</div>")
1878 })
1879}
1880
1881fn item_macro(cx: &Context<'_>, it: &clean::Item, t: &clean::Macro) -> impl fmt::Display {
1882 fmt::from_fn(|w| {
1883 wrap_item(w, |w| {
1884 render_attributes_in_code(w, it, "", cx);
1886 if !t.macro_rules {
1887 write!(w, "{}", visibility_print_with_space(it, cx))?;
1888 }
1889 write!(w, "{}", Escape(&t.source))
1890 })?;
1891 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))
1892 })
1893}
1894
1895fn item_proc_macro(cx: &Context<'_>, it: &clean::Item, m: &clean::ProcMacro) -> impl fmt::Display {
1896 fmt::from_fn(|w| {
1897 wrap_item(w, |w| {
1898 let name = it.name.expect("proc-macros always have names");
1899 match m.kind {
1900 MacroKind::Bang => {
1901 write!(w, "{name}!() {{ <span class=\"comment\">/* proc-macro */</span> }}")?;
1902 }
1903 MacroKind::Attr => {
1904 write!(w, "#[{name}]")?;
1905 }
1906 MacroKind::Derive => {
1907 write!(w, "#[derive({name})]")?;
1908 if !m.helpers.is_empty() {
1909 w.write_str(
1910 "\n{\n \
1911 <span class=\"comment\">// Attributes available to this derive:</span>\n",
1912 )?;
1913 for attr in &m.helpers {
1914 writeln!(w, " #[{attr}]")?;
1915 }
1916 w.write_str("}\n")?;
1917 }
1918 }
1919 }
1920 fmt::Result::Ok(())
1921 })?;
1922 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))
1923 })
1924}
1925
1926fn item_primitive(cx: &Context<'_>, it: &clean::Item) -> impl fmt::Display {
1927 fmt::from_fn(|w| {
1928 let def_id = it.item_id.expect_def_id();
1929 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))?;
1930 if it.name.map(|n| n.as_str() != "reference").unwrap_or(false) {
1931 write!(w, "{}", render_assoc_items(cx, it, def_id, AssocItemRender::All))?;
1932 } else {
1933 let (concrete, synthetic, blanket_impl) =
1936 get_filtered_impls_for_reference(&cx.shared, it);
1937
1938 render_all_impls(w, cx, it, &concrete, &synthetic, &blanket_impl);
1939 }
1940 Ok(())
1941 })
1942}
1943
1944fn item_constant(
1945 cx: &Context<'_>,
1946 it: &clean::Item,
1947 generics: &clean::Generics,
1948 ty: &clean::Type,
1949 c: &clean::ConstantKind,
1950) -> impl fmt::Display {
1951 fmt::from_fn(|w| {
1952 wrap_item(w, |w| {
1953 let tcx = cx.tcx();
1954 render_attributes_in_code(w, it, "", cx);
1955
1956 write!(
1957 w,
1958 "{vis}const {name}{generics}: {typ}{where_clause}",
1959 vis = visibility_print_with_space(it, cx),
1960 name = it.name.unwrap(),
1961 generics = generics.print(cx),
1962 typ = ty.print(cx),
1963 where_clause =
1964 print_where_clause(generics, cx, 0, Ending::NoNewline).maybe_display(),
1965 )?;
1966
1967 let value = c.value(tcx);
1977 let is_literal = c.is_literal(tcx);
1978 let expr = c.expr(tcx);
1979 if value.is_some() || is_literal {
1980 write!(w, " = {expr};", expr = Escape(&expr))?;
1981 } else {
1982 w.write_str(";")?;
1983 }
1984
1985 if !is_literal && let Some(value) = &value {
1986 let value_lowercase = value.to_lowercase();
1987 let expr_lowercase = expr.to_lowercase();
1988
1989 if value_lowercase != expr_lowercase
1990 && value_lowercase.trim_end_matches("i32") != expr_lowercase
1991 {
1992 write!(w, " // {value}", value = Escape(value))?;
1993 }
1994 }
1995 Ok::<(), fmt::Error>(())
1996 })?;
1997
1998 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))
1999 })
2000}
2001
2002struct DisplayStruct<'a> {
2003 ctor_kind: Option<CtorKind>,
2004 generics: &'a clean::Generics,
2005 fields: &'a [clean::Item],
2006 def_id: DefId,
2007}
2008
2009impl<'a> DisplayStruct<'a> {
2010 fn render_into<W: fmt::Write>(
2011 self,
2012 cx: &Context<'_>,
2013 it: &clean::Item,
2014 is_type_alias: bool,
2015 w: &mut W,
2016 ) -> fmt::Result {
2017 wrap_item(w, |w| {
2018 if is_type_alias {
2019 render_repr_attribute_in_code(w, cx, self.def_id);
2021 } else {
2022 render_attributes_in_code(w, it, "", cx);
2023 }
2024 write!(
2025 w,
2026 "{}",
2027 render_struct(it, Some(self.generics), self.ctor_kind, self.fields, "", true, cx)
2028 )
2029 })?;
2030
2031 if !is_type_alias {
2032 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))?;
2033 }
2034
2035 let def_id = it.item_id.expect_def_id();
2036 write!(
2037 w,
2038 "{}{}{}",
2039 item_fields(cx, it, self.fields, self.ctor_kind),
2040 render_assoc_items(cx, it, def_id, AssocItemRender::All),
2041 document_type_layout(cx, def_id),
2042 )
2043 }
2044}
2045
2046fn item_struct(cx: &Context<'_>, it: &clean::Item, s: &clean::Struct) -> impl fmt::Display {
2047 fmt::from_fn(|w| {
2048 DisplayStruct {
2049 ctor_kind: s.ctor_kind,
2050 generics: &s.generics,
2051 fields: s.fields.as_slice(),
2052 def_id: it.def_id().unwrap(),
2053 }
2054 .render_into(cx, it, false, w)
2055 })
2056}
2057
2058fn item_fields(
2059 cx: &Context<'_>,
2060 it: &clean::Item,
2061 fields: &[clean::Item],
2062 ctor_kind: Option<CtorKind>,
2063) -> impl fmt::Display {
2064 fmt::from_fn(move |w| {
2065 let mut fields = fields
2066 .iter()
2067 .filter_map(|f| match f.kind {
2068 clean::StructFieldItem(ref ty) => Some((f, ty)),
2069 _ => None,
2070 })
2071 .peekable();
2072 if let None | Some(CtorKind::Fn) = ctor_kind
2073 && fields.peek().is_some()
2074 {
2075 let title = format!(
2076 "{}{}",
2077 if ctor_kind.is_none() { "Fields" } else { "Tuple Fields" },
2078 document_non_exhaustive_header(it),
2079 );
2080 write!(
2081 w,
2082 "{}",
2083 write_section_heading(
2084 &title,
2085 "fields",
2086 Some("fields"),
2087 document_non_exhaustive(it)
2088 )
2089 )?;
2090 for (index, (field, ty)) in fields.enumerate() {
2091 let field_name =
2092 field.name.map_or_else(|| index.to_string(), |sym| sym.as_str().to_string());
2093 let id = cx.derive_id(format!("{typ}.{field_name}", typ = ItemType::StructField));
2094 write!(
2095 w,
2096 "<span id=\"{id}\" class=\"{item_type} section-header\">\
2097 <a href=\"#{id}\" class=\"anchor field\">§</a>\
2098 <code>",
2099 item_type = ItemType::StructField,
2100 )?;
2101 render_attributes_in_code(w, field, "", cx);
2102 write!(
2103 w,
2104 "{field_name}: {ty}</code>\
2105 </span>\
2106 {doc}",
2107 ty = ty.print(cx),
2108 doc = document(cx, field, Some(it), HeadingOffset::H3),
2109 )?;
2110 }
2111 }
2112 Ok(())
2113 })
2114}
2115
2116fn item_static(
2117 cx: &Context<'_>,
2118 it: &clean::Item,
2119 s: &clean::Static,
2120 safety: Option<hir::Safety>,
2121) -> impl fmt::Display {
2122 fmt::from_fn(move |w| {
2123 wrap_item(w, |w| {
2124 render_attributes_in_code(w, it, "", cx);
2125 write!(
2126 w,
2127 "{vis}{safe}static {mutability}{name}: {typ}",
2128 vis = visibility_print_with_space(it, cx),
2129 safe = safety.map(|safe| safe.prefix_str()).unwrap_or(""),
2130 mutability = s.mutability.print_with_space(),
2131 name = it.name.unwrap(),
2132 typ = s.type_.print(cx)
2133 )
2134 })?;
2135
2136 write!(w, "{}", document(cx, it, None, HeadingOffset::H2))
2137 })
2138}
2139
2140fn item_foreign_type(cx: &Context<'_>, it: &clean::Item) -> impl fmt::Display {
2141 fmt::from_fn(|w| {
2142 wrap_item(w, |w| {
2143 w.write_str("extern {\n")?;
2144 render_attributes_in_code(w, it, "", cx);
2145 write!(w, " {}type {};\n}}", visibility_print_with_space(it, cx), it.name.unwrap(),)
2146 })?;
2147
2148 write!(
2149 w,
2150 "{}{}",
2151 document(cx, it, None, HeadingOffset::H2),
2152 render_assoc_items(cx, it, it.item_id.expect_def_id(), AssocItemRender::All)
2153 )
2154 })
2155}
2156
2157fn item_keyword_or_attribute(cx: &Context<'_>, it: &clean::Item) -> impl fmt::Display {
2158 document(cx, it, None, HeadingOffset::H2)
2159}
2160
2161pub(crate) fn compare_names(left: &str, right: &str) -> Ordering {
2167 let mut left = left.chars().peekable();
2168 let mut right = right.chars().peekable();
2169
2170 loop {
2171 let (l, r) = match (left.next(), right.next()) {
2173 (None, None) => return Ordering::Equal,
2175 (None, Some(_)) => return Ordering::Less,
2177 (Some(_), None) => return Ordering::Greater,
2178 (Some(l), Some(r)) => (l, r),
2179 };
2180 let next_ordering = match (l.to_digit(10), r.to_digit(10)) {
2181 (None, None) => Ord::cmp(&l, &r),
2183 (None, Some(_)) => Ordering::Greater,
2186 (Some(_), None) => Ordering::Less,
2187 (Some(l), Some(r)) => {
2189 if l == 0 || r == 0 {
2190 let ordering = Ord::cmp(&l, &r);
2192 if ordering != Ordering::Equal {
2193 return ordering;
2194 }
2195 loop {
2196 let (l, r) = match (left.peek(), right.peek()) {
2198 (None, None) => return Ordering::Equal,
2200 (None, Some(_)) => return Ordering::Less,
2202 (Some(_), None) => return Ordering::Greater,
2203 (Some(l), Some(r)) => (l, r),
2204 };
2205 match (l.to_digit(10), r.to_digit(10)) {
2207 (None, None) => break Ordering::Equal,
2209 (None, Some(_)) => return Ordering::Less,
2211 (Some(_), None) => return Ordering::Greater,
2212 (Some(l), Some(r)) => {
2214 left.next();
2215 right.next();
2216 let ordering = Ord::cmp(&l, &r);
2217 if ordering != Ordering::Equal {
2218 return ordering;
2219 }
2220 }
2221 }
2222 }
2223 } else {
2224 let mut same_length_ordering = Ord::cmp(&l, &r);
2226 loop {
2227 let (l, r) = match (left.peek(), right.peek()) {
2229 (None, None) => return same_length_ordering,
2231 (None, Some(_)) => return Ordering::Less,
2233 (Some(_), None) => return Ordering::Greater,
2234 (Some(l), Some(r)) => (l, r),
2235 };
2236 match (l.to_digit(10), r.to_digit(10)) {
2238 (None, None) => break same_length_ordering,
2240 (None, Some(_)) => return Ordering::Less,
2242 (Some(_), None) => return Ordering::Greater,
2243 (Some(l), Some(r)) => {
2245 left.next();
2246 right.next();
2247 same_length_ordering = same_length_ordering.then(Ord::cmp(&l, &r));
2248 }
2249 }
2250 }
2251 }
2252 }
2253 };
2254 if next_ordering != Ordering::Equal {
2255 return next_ordering;
2256 }
2257 }
2258}
2259
2260pub(super) fn full_path(cx: &Context<'_>, item: &clean::Item) -> String {
2261 let mut s = join_path_syms(&cx.current);
2262 s.push_str("::");
2263 s.push_str(item.name.unwrap().as_str());
2264 s
2265}
2266
2267pub(super) fn print_item_path(ty: ItemType, name: &str) -> impl Display {
2268 fmt::from_fn(move |f| match ty {
2269 ItemType::Module => write!(f, "{}index.html", ensure_trailing_slash(name)),
2270 _ => write!(f, "{ty}.{name}.html"),
2271 })
2272}
2273
2274fn print_bounds(
2275 bounds: &[clean::GenericBound],
2276 trait_alias: bool,
2277 cx: &Context<'_>,
2278) -> impl Display {
2279 (!bounds.is_empty())
2280 .then_some(fmt::from_fn(move |f| {
2281 let has_lots_of_bounds = bounds.len() > 2;
2282 let inter_str = if has_lots_of_bounds { "\n + " } else { " + " };
2283 if !trait_alias {
2284 if has_lots_of_bounds {
2285 f.write_str(":\n ")?;
2286 } else {
2287 f.write_str(": ")?;
2288 }
2289 }
2290
2291 bounds.iter().map(|p| p.print(cx)).joined(inter_str, f)
2292 }))
2293 .maybe_display()
2294}
2295
2296fn wrap_item<W, F, T>(w: &mut W, f: F) -> T
2297where
2298 W: fmt::Write,
2299 F: FnOnce(&mut W) -> T,
2300{
2301 write!(w, r#"<pre class="rust item-decl"><code>"#).unwrap();
2302 let res = f(w);
2303 write!(w, "</code></pre>").unwrap();
2304 res
2305}
2306
2307#[derive(PartialEq, Eq)]
2308struct ImplString(String);
2309
2310impl ImplString {
2311 fn new(i: &Impl, cx: &Context<'_>) -> ImplString {
2312 ImplString(format!("{}", i.inner_impl().print(false, cx)))
2313 }
2314}
2315
2316impl PartialOrd for ImplString {
2317 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
2318 Some(Ord::cmp(self, other))
2319 }
2320}
2321
2322impl Ord for ImplString {
2323 fn cmp(&self, other: &Self) -> Ordering {
2324 compare_names(&self.0, &other.0)
2325 }
2326}
2327
2328fn render_implementor(
2329 cx: &Context<'_>,
2330 implementor: &Impl,
2331 trait_: &clean::Item,
2332 implementor_dups: &FxHashMap<Symbol, (DefId, bool)>,
2333 aliases: &[String],
2334) -> impl fmt::Display {
2335 let use_absolute = match implementor.inner_impl().for_ {
2338 clean::Type::Path { ref path, .. }
2339 | clean::BorrowedRef { type_: box clean::Type::Path { ref path, .. }, .. }
2340 if !path.is_assoc_ty() =>
2341 {
2342 implementor_dups[&path.last()].1
2343 }
2344 _ => false,
2345 };
2346 render_impl(
2347 cx,
2348 implementor,
2349 trait_,
2350 AssocItemLink::Anchor(None),
2351 RenderMode::Normal,
2352 Some(use_absolute),
2353 aliases,
2354 ImplRenderingParameters {
2355 show_def_docs: false,
2356 show_default_items: false,
2357 show_non_assoc_items: false,
2358 toggle_open_by_default: false,
2359 },
2360 )
2361}
2362
2363fn render_union(
2364 it: &clean::Item,
2365 g: Option<&clean::Generics>,
2366 fields: &[clean::Item],
2367 def_id: DefId,
2368 is_type_alias: bool,
2369 cx: &Context<'_>,
2370) -> impl Display {
2371 fmt::from_fn(move |mut f| {
2372 if is_type_alias {
2373 render_repr_attribute_in_code(f, cx, def_id);
2375 } else {
2376 render_attributes_in_code(f, it, "", cx);
2377 }
2378 write!(f, "{}union {}", visibility_print_with_space(it, cx), it.name.unwrap(),)?;
2379
2380 let where_displayed = if let Some(generics) = g {
2381 write!(f, "{}", generics.print(cx))?;
2382 if let Some(where_clause) = print_where_clause(generics, cx, 0, Ending::Newline) {
2383 write!(f, "{where_clause}")?;
2384 true
2385 } else {
2386 false
2387 }
2388 } else {
2389 false
2390 };
2391
2392 if !where_displayed {
2394 f.write_str(" ")?;
2395 }
2396
2397 writeln!(f, "{{")?;
2398 let count_fields =
2399 fields.iter().filter(|field| matches!(field.kind, clean::StructFieldItem(..))).count();
2400 let toggle = should_hide_fields(count_fields);
2401 if toggle {
2402 toggle_open(&mut f, format_args!("{count_fields} fields"));
2403 }
2404
2405 for field in fields {
2406 if let clean::StructFieldItem(ref ty) = field.kind {
2407 render_attributes_in_code(&mut f, field, " ", cx);
2408 writeln!(
2409 f,
2410 " {}{}: {},",
2411 visibility_print_with_space(field, cx),
2412 field.name.unwrap(),
2413 ty.print(cx)
2414 )?;
2415 }
2416 }
2417
2418 if it.has_stripped_entries().unwrap() {
2419 writeln!(f, " <span class=\"comment\">/* private fields */</span>")?;
2420 }
2421 if toggle {
2422 toggle_close(&mut f);
2423 }
2424 f.write_str("}").unwrap();
2425 Ok(())
2426 })
2427}
2428
2429fn render_struct(
2430 it: &clean::Item,
2431 g: Option<&clean::Generics>,
2432 ty: Option<CtorKind>,
2433 fields: &[clean::Item],
2434 tab: &str,
2435 structhead: bool,
2436 cx: &Context<'_>,
2437) -> impl fmt::Display {
2438 fmt::from_fn(move |w| {
2439 write!(
2440 w,
2441 "{}{}{}",
2442 visibility_print_with_space(it, cx),
2443 if structhead { "struct " } else { "" },
2444 it.name.unwrap()
2445 )?;
2446 if let Some(g) = g {
2447 write!(w, "{}", g.print(cx))?;
2448 }
2449 write!(
2450 w,
2451 "{}",
2452 render_struct_fields(
2453 g,
2454 ty,
2455 fields,
2456 tab,
2457 structhead,
2458 it.has_stripped_entries().unwrap_or(false),
2459 cx,
2460 )
2461 )
2462 })
2463}
2464
2465fn render_struct_fields(
2466 g: Option<&clean::Generics>,
2467 ty: Option<CtorKind>,
2468 fields: &[clean::Item],
2469 tab: &str,
2470 structhead: bool,
2471 has_stripped_entries: bool,
2472 cx: &Context<'_>,
2473) -> impl fmt::Display {
2474 fmt::from_fn(move |w| {
2475 match ty {
2476 None => {
2477 let where_displayed = if let Some(generics) = g
2478 && let Some(where_clause) = print_where_clause(generics, cx, 0, Ending::Newline)
2479 {
2480 write!(w, "{where_clause}")?;
2481 true
2482 } else {
2483 false
2484 };
2485
2486 if !where_displayed {
2488 w.write_str(" {")?;
2489 } else {
2490 w.write_str("{")?;
2491 }
2492 let count_fields =
2493 fields.iter().filter(|f| matches!(f.kind, clean::StructFieldItem(..))).count();
2494 let has_visible_fields = count_fields > 0;
2495 let toggle = should_hide_fields(count_fields);
2496 if toggle {
2497 toggle_open(&mut *w, format_args!("{count_fields} fields"));
2498 }
2499 if has_visible_fields {
2500 writeln!(w)?;
2501 }
2502 for field in fields {
2503 if let clean::StructFieldItem(ref ty) = field.kind {
2504 render_attributes_in_code(w, field, &format!("{tab} "), cx);
2505 writeln!(
2506 w,
2507 "{tab} {vis}{name}: {ty},",
2508 vis = visibility_print_with_space(field, cx),
2509 name = field.name.unwrap(),
2510 ty = ty.print(cx)
2511 )?;
2512 }
2513 }
2514
2515 if has_visible_fields {
2516 if has_stripped_entries {
2517 writeln!(
2518 w,
2519 "{tab} <span class=\"comment\">/* private fields */</span>"
2520 )?;
2521 }
2522 write!(w, "{tab}")?;
2523 } else if has_stripped_entries {
2524 write!(w, " <span class=\"comment\">/* private fields */</span> ")?;
2525 }
2526 if toggle {
2527 toggle_close(&mut *w);
2528 }
2529 w.write_str("}")?;
2530 }
2531 Some(CtorKind::Fn) => {
2532 w.write_str("(")?;
2533 if !fields.is_empty()
2534 && fields.iter().all(|field| {
2535 matches!(field.kind, clean::StrippedItem(box clean::StructFieldItem(..)))
2536 })
2537 {
2538 write!(w, "<span class=\"comment\">/* private fields */</span>")?;
2539 } else {
2540 for (i, field) in fields.iter().enumerate() {
2541 if i > 0 {
2542 w.write_str(", ")?;
2543 }
2544 match field.kind {
2545 clean::StrippedItem(box clean::StructFieldItem(..)) => {
2546 write!(w, "_")?;
2547 }
2548 clean::StructFieldItem(ref ty) => {
2549 write!(
2550 w,
2551 "{}{}",
2552 visibility_print_with_space(field, cx),
2553 ty.print(cx)
2554 )?;
2555 }
2556 _ => unreachable!(),
2557 }
2558 }
2559 }
2560 w.write_str(")")?;
2561 if let Some(g) = g {
2562 write!(
2563 w,
2564 "{}",
2565 print_where_clause(g, cx, 0, Ending::NoNewline).maybe_display()
2566 )?;
2567 }
2568 if structhead {
2570 w.write_str(";")?;
2571 }
2572 }
2573 Some(CtorKind::Const) => {
2574 if let Some(g) = g {
2576 write!(
2577 w,
2578 "{}",
2579 print_where_clause(g, cx, 0, Ending::NoNewline).maybe_display()
2580 )?;
2581 }
2582 w.write_str(";")?;
2583 }
2584 }
2585 Ok(())
2586 })
2587}
2588
2589fn document_non_exhaustive_header(item: &clean::Item) -> &str {
2590 if item.is_non_exhaustive() { " (Non-exhaustive)" } else { "" }
2591}
2592
2593fn document_non_exhaustive(item: &clean::Item) -> impl Display {
2594 fmt::from_fn(|f| {
2595 if item.is_non_exhaustive() {
2596 write!(
2597 f,
2598 "<details class=\"toggle non-exhaustive\">\
2599 <summary class=\"hideme\"><span>{}</span></summary>\
2600 <div class=\"docblock\">",
2601 {
2602 if item.is_struct() {
2603 "This struct is marked as non-exhaustive"
2604 } else if item.is_enum() {
2605 "This enum is marked as non-exhaustive"
2606 } else if item.is_variant() {
2607 "This variant is marked as non-exhaustive"
2608 } else {
2609 "This type is marked as non-exhaustive"
2610 }
2611 }
2612 )?;
2613
2614 if item.is_struct() {
2615 f.write_str(
2616 "Non-exhaustive structs could have additional fields added in future. \
2617 Therefore, non-exhaustive structs cannot be constructed in external crates \
2618 using the traditional <code>Struct { .. }</code> syntax; cannot be \
2619 matched against without a wildcard <code>..</code>; and \
2620 struct update syntax will not work.",
2621 )?;
2622 } else if item.is_enum() {
2623 f.write_str(
2624 "Non-exhaustive enums could have additional variants added in future. \
2625 Therefore, when matching against variants of non-exhaustive enums, an \
2626 extra wildcard arm must be added to account for any future variants.",
2627 )?;
2628 } else if item.is_variant() {
2629 f.write_str(
2630 "Non-exhaustive enum variants could have additional fields added in future. \
2631 Therefore, non-exhaustive enum variants cannot be constructed in external \
2632 crates and cannot be matched against.",
2633 )?;
2634 } else {
2635 f.write_str(
2636 "This type will require a wildcard arm in any match statements or constructors.",
2637 )?;
2638 }
2639
2640 f.write_str("</div></details>")?;
2641 }
2642 Ok(())
2643 })
2644}
2645
2646fn pluralize(count: usize) -> &'static str {
2647 if count > 1 { "s" } else { "" }
2648}