public_api/
public_item.rs

1use rustdoc_types::Id;
2use std::cmp::Ordering;
3use std::fmt::Display;
4use std::hash::Hash;
5
6use crate::intermediate_public_item::IntermediatePublicItem;
7use crate::render::RenderingContext;
8use crate::tokens::tokens_to_string;
9use crate::tokens::Token;
10
11/// Each public item (except `impl`s) have a path that is displayed like
12/// `first::second::third`. Internally we represent that with a `vec!["first",
13/// "second", "third"]`. This is a type alias for that internal representation
14/// to make the code easier to read.
15pub(crate) type PublicItemPath = Vec<String>;
16
17/// Represent a public item of an analyzed crate, i.e. an item that forms part
18/// of the public API of a crate. Implements [`Display`] so it can be printed. It
19/// also implements [`Ord`], but how items are ordered are not stable yet, and
20/// will change in later versions.
21#[derive(Clone)]
22pub struct PublicItem {
23    /// Read [`crate::item_processor::sorting_prefix()`] docs for more info
24    pub(crate) sortable_path: PublicItemPath,
25
26    /// The rendered item as a stream of [`Token`]s
27    pub(crate) tokens: Vec<Token>,
28
29    /// The [`Id`] of this item's logical parent (if any)
30    pub(crate) parent_id: Option<Id>,
31
32    /// The [`Id`] to which this public item corresponds
33    pub(crate) id: Id,
34}
35
36impl PublicItem {
37    pub(crate) fn from_intermediate_public_item(
38        context: &RenderingContext,
39        public_item: &IntermediatePublicItem<'_>,
40    ) -> PublicItem {
41        PublicItem {
42            sortable_path: public_item.sortable_path(context),
43            tokens: public_item.render_token_stream(context),
44            parent_id: public_item.parent_id(),
45            id: public_item.id(),
46        }
47    }
48
49    /// The [`Id`] of this item's logical parent (if any)
50    #[must_use]
51    pub fn parent_id(&self) -> Option<Id> {
52        self.parent_id
53    }
54
55    /// The [`Id`] to which this public item corresponds
56    #[must_use]
57    pub fn id(&self) -> Id {
58        self.id
59    }
60
61    /// The rendered item as a stream of [`Token`]s
62    pub fn tokens(&self) -> impl Iterator<Item = &Token> {
63        self.tokens.iter()
64    }
65
66    /// Special version of [`cmp`](Ord::cmp) that is used to sort public items in a way that
67    /// makes them grouped logically. For example, struct fields will be put
68    /// right after the struct they are part of.
69    #[must_use]
70    pub fn grouping_cmp(&self, other: &Self) -> std::cmp::Ordering {
71        // This will make e.g. struct and struct fields be grouped together.
72        if let Some(ordering) = different_or_none(&self.sortable_path, &other.sortable_path) {
73            return ordering;
74        }
75
76        // Fall back to lexical sorting if the above is not sufficient
77        self.to_string().cmp(&other.to_string())
78    }
79}
80
81impl PartialEq for PublicItem {
82    fn eq(&self, other: &Self) -> bool {
83        self.tokens == other.tokens
84    }
85}
86
87impl Eq for PublicItem {}
88
89impl Hash for PublicItem {
90    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
91        self.tokens.hash(state);
92    }
93}
94
95/// We want pretty-printing (`"{:#?}"`) of [`crate::diff::PublicApiDiff`] to print
96/// each public item as `Display`, so implement `Debug` with `Display`.
97impl std::fmt::Debug for PublicItem {
98    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
99        std::fmt::Display::fmt(self, f)
100    }
101}
102
103/// One of the basic uses cases is printing a sorted `Vec` of `PublicItem`s. So
104/// we implement `Display` for it.
105impl Display for PublicItem {
106    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
107        write!(f, "{}", tokens_to_string(&self.tokens))
108    }
109}
110
111/// Returns `None` if two items are equal. Otherwise their ordering is returned.
112fn different_or_none<T: Ord>(a: &T, b: &T) -> Option<Ordering> {
113    match a.cmp(b) {
114        Ordering::Equal => None,
115        c => Some(c),
116    }
117}
public_api/public_item.rs

public_api/
public_item.rs
