rustdoc/json/
mod.rs

1//! Rustdoc's JSON backend
2//!
3//! This module contains the logic for rendering a crate as JSON rather than the normal static HTML
4//! output. See [the RFC](https://github.com/rust-lang/rfcs/pull/2963) and the [`types`] module
5//! docs for usage and details.
6
7mod conversions;
8mod ids;
9mod import_finder;
10
11use std::cell::RefCell;
12use std::fs::{File, create_dir_all};
13use std::io::{BufWriter, Write, stdout};
14use std::path::PathBuf;
15use std::rc::Rc;
16
17use rustc_hir::def::DefKind;
18use rustc_hir::def_id::{DefId, DefIdSet};
19use rustc_middle::ty::TyCtxt;
20use rustc_session::Session;
21use rustc_span::def_id::LOCAL_CRATE;
22use rustdoc_json_types as types;
23// It's important to use the FxHashMap from rustdoc_json_types here, instead of
24// the one from rustc_data_structures, as they're different types due to sysroots.
25// See #110051 and #127456 for details
26use rustdoc_json_types::FxHashMap;
27use tracing::{debug, trace};
28
29use crate::clean::ItemKind;
30use crate::clean::types::{ExternalCrate, ExternalLocation};
31use crate::config::{EmitType, RenderOptions};
32use crate::docfs::PathError;
33use crate::error::Error;
34use crate::formats::FormatRenderer;
35use crate::formats::cache::Cache;
36use crate::formats::item_type::ItemType;
37use crate::json::conversions::IntoJson;
38use crate::passes::collect_intra_doc_links::UrlFragment;
39use crate::{clean, try_err};
40
41pub(crate) struct JsonRenderer<'tcx> {
42    tcx: TyCtxt<'tcx>,
43    /// A mapping of IDs that contains all local items for this crate which gets output as a top
44    /// level field of the JSON blob.
45    index: FxHashMap<types::Id, types::Item>,
46    /// The directory where the JSON blob should be written to.
47    ///
48    /// If this is `None`, the blob will be printed to `stdout` instead.
49    out_dir: Option<PathBuf>,
50    cache: Rc<Cache>,
51    imported_items: DefIdSet,
52    id_interner: RefCell<ids::IdInterner>,
53}
54
55impl<'tcx> JsonRenderer<'tcx> {
56    fn sess(&self) -> &'tcx Session {
57        self.tcx.sess
58    }
59
60    fn get_trait_implementors(&mut self, id: DefId) -> Vec<types::Id> {
61        Rc::clone(&self.cache)
62            .implementors
63            .get(&id)
64            .map(|implementors| {
65                implementors
66                    .iter()
67                    .map(|i| {
68                        let item = &i.impl_item;
69                        self.item(item).unwrap();
70                        self.id_from_item(item)
71                    })
72                    .collect()
73            })
74            .unwrap_or_default()
75    }
76
77    fn get_impls(&mut self, id: DefId) -> Vec<types::Id> {
78        Rc::clone(&self.cache)
79            .impls
80            .get(&id)
81            .map(|impls| {
82                impls
83                    .iter()
84                    .filter_map(|i| {
85                        let item = &i.impl_item;
86
87                        // HACK(hkmatsumoto): For impls of primitive types, we index them
88                        // regardless of whether they're local. This is because users can
89                        // document primitive items in an arbitrary crate by using
90                        // `rustc_doc_primitive`.
91                        let mut is_primitive_impl = false;
92                        if let clean::types::ItemKind::ImplItem(ref impl_) = item.kind
93                            && impl_.trait_.is_none()
94                            && let clean::types::Type::Primitive(_) = impl_.for_
95                        {
96                            is_primitive_impl = true;
97                        }
98
99                        if item.item_id.is_local() || is_primitive_impl {
100                            self.item(item).unwrap();
101                            Some(self.id_from_item(item))
102                        } else {
103                            None
104                        }
105                    })
106                    .collect()
107            })
108            .unwrap_or_default()
109    }
110
111    fn paths(&self) -> FxHashMap<types::Id, types::ItemSummary> {
112        let mut paths = self
113            .cache
114            .paths
115            .iter()
116            .map(|(k, info)| (k, (&info.parts, info.ty)))
117            .chain(self.cache.external_paths.iter().map(|(k, (parts, ty))| (k, (parts, *ty))))
118            .map(|(&k, (path, kind))| {
119                (
120                    self.id_from_item_default(k.into()),
121                    types::ItemSummary {
122                        crate_id: k.krate.as_u32(),
123                        path: path.iter().map(|s| s.to_string()).collect(),
124                        kind: kind.into_json(self),
125                    },
126                )
127            })
128            .collect();
129
130        self.add_intra_doc_link_paths(&mut paths);
131        paths
132    }
133
134    fn add_intra_doc_link_paths(&self, paths: &mut FxHashMap<types::Id, types::ItemSummary>) {
135        // The link target IDs were already interned when the `links` maps were emitted.
136        // This only fills missing summaries in `paths`, where JSON object order is not meaningful.
137        #[allow(rustc::potential_query_instability)]
138        let links = self.cache.intra_doc_links.values();
139        for link in links.flatten() {
140            let Some(UrlFragment::Item(item_id)) = link.fragment.as_ref() else {
141                continue;
142            };
143            let item_id = *item_id;
144            let id = self.id_from_item_default(item_id.into());
145
146            if paths.contains_key(&id) || (item_id.is_local() && !self.index.contains_key(&id)) {
147                continue;
148            }
149
150            let path = self.path_for_link_target(link.page_id, item_id);
151            let kind = ItemType::from_def_id(item_id, self.tcx);
152            paths.insert(
153                id,
154                types::ItemSummary {
155                    crate_id: item_id.krate.as_u32(),
156                    path,
157                    kind: kind.into_json(self),
158                },
159            );
160        }
161    }
162
163    fn path_for_link_target(&self, page_id: DefId, item_id: DefId) -> Vec<String> {
164        let parent_id = self.tcx.parent(item_id);
165        // Inherent items have an unnamed impl parent, while variant fields have one extra named
166        // parent between themselves and their page.
167        let (mut path, variant_id) = match self.tcx.def_kind(parent_id) {
168            DefKind::Impl { .. } => (
169                self.cached_path(page_id).expect("intra-doc link page should have a cached path"),
170                None,
171            ),
172            DefKind::Variant => {
173                (self.path_for_named_item(self.tcx.parent(parent_id)), Some(parent_id))
174            }
175            _ => (self.path_for_named_item(parent_id), None),
176        };
177
178        if let Some(variant_id) = variant_id {
179            path.push(self.tcx.item_name(variant_id).to_string());
180        }
181        path.push(self.tcx.item_name(item_id).to_string());
182        path
183    }
184
185    fn path_for_named_item(&self, item_id: DefId) -> Vec<String> {
186        self.cached_path(item_id).unwrap_or_else(|| {
187            let kind = ItemType::from_def_id(item_id, self.tcx);
188            clean::inline::get_item_path(self.tcx, item_id, kind)
189                .into_iter()
190                .map(|name| name.to_string())
191                .collect()
192        })
193    }
194
195    fn cached_path(&self, item_id: DefId) -> Option<Vec<String>> {
196        self.cache
197            .paths
198            .get(&item_id)
199            .map(|info| &info.parts)
200            .or_else(|| self.cache.external_paths.get(&item_id).map(|(parts, _)| parts))
201            .map(|path| path.iter().map(|name| name.to_string()).collect())
202    }
203}
204
205impl<'tcx> JsonRenderer<'tcx> {
206    pub(crate) fn init(
207        krate: clean::Crate,
208        options: RenderOptions,
209        cache: Cache,
210        tcx: TyCtxt<'tcx>,
211    ) -> Result<(Self, clean::Crate), Error> {
212        debug!("Initializing json renderer");
213
214        let (krate, imported_items) = import_finder::get_imports(krate);
215
216        Ok((
217            JsonRenderer {
218                tcx,
219                index: FxHashMap::default(),
220                out_dir: if options.output_to_stdout { None } else { Some(options.output) },
221                cache: Rc::new(cache),
222                imported_items,
223                id_interner: Default::default(),
224            },
225            krate,
226        ))
227    }
228}
229
230impl<'tcx> FormatRenderer<'tcx> for JsonRenderer<'tcx> {
231    const DESCR: &'static str = "json";
232    const RUN_ON_MODULE: bool = false;
233    const NON_STATIC_FILE_EMIT_TYPE: EmitType = EmitType::IrJsonFiles;
234
235    type ModuleData = ();
236
237    fn save_module_data(&mut self) -> Self::ModuleData {
238        unreachable!("RUN_ON_MODULE = false, should never call save_module_data")
239    }
240    fn restore_module_data(&mut self, _info: Self::ModuleData) {
241        unreachable!("RUN_ON_MODULE = false, should never call set_back_info")
242    }
243
244    /// Inserts an item into the index. This should be used rather than directly calling insert on
245    /// the hashmap because certain items (traits and types) need to have their mappings for trait
246    /// implementations filled out before they're inserted.
247    fn item(&mut self, item: &clean::Item) -> Result<(), Error> {
248        use std::collections::hash_map::Entry;
249
250        let item_type = item.type_();
251        let item_name = item.name;
252        trace!("rendering {item_type} {item_name:?}");
253
254        // Flatten items that recursively store other items. We include orphaned items from
255        // stripped modules and etc that are otherwise reachable.
256        if let ItemKind::StrippedItem(inner) = &item.kind {
257            inner.inner_items().for_each(|i| self.item(i).unwrap());
258        }
259
260        // Flatten items that recursively store other items
261        item.kind.inner_items().for_each(|i| self.item(i).unwrap());
262
263        let item_id = item.item_id;
264        if let Some(mut new_item) = self.convert_item(item) {
265            let can_be_ignored = match new_item.inner {
266                types::ItemEnum::Trait(ref mut t) => {
267                    t.implementations = self.get_trait_implementors(item_id.expect_def_id());
268                    false
269                }
270                types::ItemEnum::Struct(ref mut s) => {
271                    s.impls = self.get_impls(item_id.expect_def_id());
272                    false
273                }
274                types::ItemEnum::Enum(ref mut e) => {
275                    e.impls = self.get_impls(item_id.expect_def_id());
276                    false
277                }
278                types::ItemEnum::Union(ref mut u) => {
279                    u.impls = self.get_impls(item_id.expect_def_id());
280                    false
281                }
282                types::ItemEnum::Primitive(ref mut p) => {
283                    p.impls = self.get_impls(item_id.expect_def_id());
284                    false
285                }
286
287                types::ItemEnum::Function(_)
288                | types::ItemEnum::Module(_)
289                | types::ItemEnum::Use(_)
290                | types::ItemEnum::AssocConst { .. }
291                | types::ItemEnum::AssocType { .. } => true,
292                types::ItemEnum::ExternCrate { .. }
293                | types::ItemEnum::StructField(_)
294                | types::ItemEnum::Variant(_)
295                | types::ItemEnum::TraitAlias(_)
296                | types::ItemEnum::Impl(_)
297                | types::ItemEnum::TypeAlias(_)
298                | types::ItemEnum::Constant { .. }
299                | types::ItemEnum::Static(_)
300                | types::ItemEnum::ExternType
301                | types::ItemEnum::Macro(_)
302                | types::ItemEnum::ProcMacro(_) => false,
303            };
304
305            // FIXME(adotinthevoid): Currently, the index is duplicated. This is a sanity check
306            // to make sure the items are unique. The main place this happens is when an item, is
307            // reexported in more than one place. See `rustdoc-json/reexport/in_root_and_mod`
308            match self.index.entry(new_item.id) {
309                Entry::Vacant(entry) => {
310                    entry.insert(new_item);
311                }
312                Entry::Occupied(mut entry) => {
313                    // In case of generic implementations (like `impl<T> Trait for T {}`), all the
314                    // inner items will be duplicated so we can ignore if they are slightly
315                    // different.
316                    let old_item = entry.get_mut();
317                    if !can_be_ignored {
318                        assert_eq!(*old_item, new_item);
319                    }
320                    trace!("replaced {old_item:?}\nwith {new_item:?}");
321                    *old_item = new_item;
322                }
323            }
324        }
325
326        trace!("done rendering {item_type} {item_name:?}");
327        Ok(())
328    }
329
330    fn mod_item_in(&mut self, _item: &clean::Item) -> Result<(), Error> {
331        unreachable!("RUN_ON_MODULE = false, should never call mod_item_in")
332    }
333
334    fn after_krate(self) -> Result<(), Error> {
335        debug!("Done with crate");
336
337        let e = ExternalCrate { crate_num: LOCAL_CRATE };
338        let sess = self.sess();
339
340        // Note that tcx.rust_target_features is inappropriate here because rustdoc tries to run for
341        // multiple targets: https://github.com/rust-lang/rust/pull/137632
342        //
343        // We want to describe a single target, so pass tcx.sess rather than tcx.
344        let target = conversions::target(sess);
345
346        debug!("Constructing Output");
347        let paths = self.paths();
348        let output_crate = types::Crate {
349            root: self.id_from_item_default(e.def_id().into()),
350            crate_version: self.cache.crate_version.clone(),
351            includes_private: self.cache.document_private,
352            paths,
353            external_crates: self
354                .cache
355                .extern_locations
356                .iter()
357                .map(|(crate_num, external_location)| {
358                    let e = ExternalCrate { crate_num: *crate_num };
359                    (
360                        crate_num.as_u32(),
361                        types::ExternalCrate {
362                            name: e.name(self.tcx).to_string(),
363                            html_root_url: match external_location {
364                                // FIXME: relative extern URLs are not resolved here
365                                ExternalLocation::Remote { url, .. } => Some(url.clone()),
366                                _ => None,
367                            },
368                            path: self
369                                .tcx
370                                .used_crate_source(*crate_num)
371                                .paths()
372                                .next()
373                                .expect("crate should have at least 1 path")
374                                .clone(),
375                        },
376                    )
377                })
378                .collect(),
379            // Be careful to not clone the `index`, it is big.
380            index: self.index,
381            target,
382            format_version: types::FORMAT_VERSION,
383        };
384        if let Some(ref out_dir) = self.out_dir {
385            try_err!(create_dir_all(out_dir), out_dir);
386
387            let mut p = out_dir.clone();
388            p.push(output_crate.index.get(&output_crate.root).unwrap().name.clone().unwrap());
389            p.set_extension("json");
390
391            serialize_and_write(
392                sess,
393                output_crate,
394                try_err!(File::create_buffered(&p), p),
395                &p.display().to_string(),
396            )
397        } else {
398            serialize_and_write(sess, output_crate, BufWriter::new(stdout().lock()), "<stdout>")
399        }
400    }
401}
402
403fn serialize_and_write<T: Write>(
404    sess: &Session,
405    output_crate: types::Crate,
406    mut writer: BufWriter<T>,
407    path: &str,
408) -> Result<(), Error> {
409    sess.time("rustdoc_json_serialize_and_write", || {
410        try_err!(
411            serde_json::ser::to_writer(&mut writer, &output_crate).map_err(|e| e.to_string()),
412            path
413        );
414        try_err!(writer.flush(), path);
415        Ok(())
416    })
417}
418
419// Some nodes are used a lot. Make sure they don't unintentionally get bigger.
420//
421// These assertions are here, not in `src/rustdoc-json-types/lib.rs` where the types are defined,
422// because we have access to `static_assert_size` here.
423#[cfg(target_pointer_width = "64")]
424mod size_asserts {
425    use rustc_data_structures::static_assert_size;
426
427    use super::types::*;
428    // tidy-alphabetical-start
429    static_assert_size!(AssocItemConstraint, 112);
430    static_assert_size!(Crate, 184);
431    static_assert_size!(FunctionPointer, 168);
432    static_assert_size!(GenericArg, 80);
433    static_assert_size!(GenericArgs, 104);
434    static_assert_size!(GenericBound, 72);
435    static_assert_size!(GenericParamDef, 136);
436    static_assert_size!(Impl, 304);
437    static_assert_size!(ItemSummary, 32);
438    static_assert_size!(PolyTrait, 64);
439    static_assert_size!(PreciseCapturingArg, 32);
440    static_assert_size!(TargetFeature, 80);
441    static_assert_size!(Type, 80);
442    static_assert_size!(WherePredicate, 160);
443    // tidy-alphabetical-end
444
445    // These contains a `PathBuf`, which is different sizes on different OSes.
446    static_assert_size!(Item, 544 + size_of::<std::path::PathBuf>());
447    static_assert_size!(ExternalCrate, 48 + size_of::<std::path::PathBuf>());
448}
rustdoc/json/mod.rs

rustdoc/json/
mod.rs
