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