aboutsummaryrefslogtreecommitdiff
path: root/crates/hir/src/doc_links.rs
diff options
context:
space:
mode:
Diffstat (limited to 'crates/hir/src/doc_links.rs')
-rw-r--r--crates/hir/src/doc_links.rs238
1 files changed, 0 insertions, 238 deletions
diff --git a/crates/hir/src/doc_links.rs b/crates/hir/src/doc_links.rs
deleted file mode 100644
index ddaffbec2..000000000
--- a/crates/hir/src/doc_links.rs
+++ /dev/null
@@ -1,238 +0,0 @@
1//! Resolves links in markdown documentation.
2
3use std::iter::once;
4
5use hir_def::resolver::Resolver;
6use itertools::Itertools;
7use syntax::ast::Path;
8use url::Url;
9
10use crate::{db::HirDatabase, Adt, AsName, Crate, Hygiene, ItemInNs, ModPath, ModuleDef};
11
12pub fn resolve_doc_link<T: Resolvable + Clone>(
13 db: &dyn HirDatabase,
14 definition: &T,
15 link_text: &str,
16 link_target: &str,
17) -> Option<(String, String)> {
18 let resolver = definition.resolver(db)?;
19 let module_def = definition.clone().try_into_module_def();
20 resolve_doc_link_impl(db, &resolver, module_def, link_text, link_target)
21}
22
23fn resolve_doc_link_impl(
24 db: &dyn HirDatabase,
25 resolver: &Resolver,
26 module_def: Option<ModuleDef>,
27 link_text: &str,
28 link_target: &str,
29) -> Option<(String, String)> {
30 try_resolve_intra(db, &resolver, link_text, &link_target).or_else(|| {
31 try_resolve_path(db, &module_def?, &link_target)
32 .map(|target| (target, link_text.to_string()))
33 })
34}
35
36/// Try to resolve path to local documentation via intra-doc-links (i.e. `super::gateway::Shard`).
37///
38/// See [RFC1946](https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md).
39fn try_resolve_intra(
40 db: &dyn HirDatabase,
41 resolver: &Resolver,
42 link_text: &str,
43 link_target: &str,
44) -> Option<(String, String)> {
45 // Set link_target for implied shortlinks
46 let link_target =
47 if link_target.is_empty() { link_text.trim_matches('`') } else { link_target };
48
49 let doclink = IntraDocLink::from(link_target);
50
51 // Parse link as a module path
52 let path = Path::parse(doclink.path).ok()?;
53 let modpath = ModPath::from_src(path, &Hygiene::new_unhygienic()).unwrap();
54
55 let resolved = resolver.resolve_module_path_in_items(db.upcast(), &modpath);
56 let (defid, namespace) = match doclink.namespace {
57 // FIXME: .or(resolved.macros)
58 None => resolved
59 .types
60 .map(|t| (t.0, Namespace::Types))
61 .or(resolved.values.map(|t| (t.0, Namespace::Values)))?,
62 Some(ns @ Namespace::Types) => (resolved.types?.0, ns),
63 Some(ns @ Namespace::Values) => (resolved.values?.0, ns),
64 // FIXME:
65 Some(Namespace::Macros) => return None,
66 };
67
68 // Get the filepath of the final symbol
69 let def: ModuleDef = defid.into();
70 let module = def.module(db)?;
71 let krate = module.krate();
72 let ns = match namespace {
73 Namespace::Types => ItemInNs::Types(defid),
74 Namespace::Values => ItemInNs::Values(defid),
75 // FIXME:
76 Namespace::Macros => None?,
77 };
78 let import_map = db.import_map(krate.into());
79 let path = import_map.path_of(ns)?;
80
81 Some((
82 get_doc_url(db, &krate)?
83 .join(&format!("{}/", krate.display_name(db)?))
84 .ok()?
85 .join(&path.segments.iter().map(|name| name.to_string()).join("/"))
86 .ok()?
87 .join(&get_symbol_filename(db, &def)?)
88 .ok()?
89 .into_string(),
90 strip_prefixes_suffixes(link_text).to_string(),
91 ))
92}
93
94/// Try to resolve path to local documentation via path-based links (i.e. `../gateway/struct.Shard.html`).
95fn try_resolve_path(db: &dyn HirDatabase, moddef: &ModuleDef, link_target: &str) -> Option<String> {
96 if !link_target.contains("#") && !link_target.contains(".html") {
97 return None;
98 }
99 let ns = ItemInNs::Types(moddef.clone().into());
100
101 let module = moddef.module(db)?;
102 let krate = module.krate();
103 let import_map = db.import_map(krate.into());
104 let base = once(format!("{}", krate.display_name(db)?))
105 .chain(import_map.path_of(ns)?.segments.iter().map(|name| format!("{}", name)))
106 .join("/");
107
108 get_doc_url(db, &krate)
109 .and_then(|url| url.join(&base).ok())
110 .and_then(|url| {
111 get_symbol_filename(db, moddef).as_deref().map(|f| url.join(f).ok()).flatten()
112 })
113 .and_then(|url| url.join(link_target).ok())
114 .map(|url| url.into_string())
115}
116
117/// Strip prefixes, suffixes, and inline code marks from the given string.
118fn strip_prefixes_suffixes(mut s: &str) -> &str {
119 s = s.trim_matches('`');
120
121 [
122 (TYPES.0.iter(), TYPES.1.iter()),
123 (VALUES.0.iter(), VALUES.1.iter()),
124 (MACROS.0.iter(), MACROS.1.iter()),
125 ]
126 .iter()
127 .for_each(|(prefixes, suffixes)| {
128 prefixes.clone().for_each(|prefix| s = s.trim_start_matches(*prefix));
129 suffixes.clone().for_each(|suffix| s = s.trim_end_matches(*suffix));
130 });
131 let s = s.trim_start_matches("@").trim();
132 s
133}
134
135fn get_doc_url(db: &dyn HirDatabase, krate: &Crate) -> Option<Url> {
136 krate
137 .get_html_root_url(db)
138 .or_else(||
139 // Fallback to docs.rs
140 // FIXME: Specify an exact version here. This may be difficult, as multiple versions of the same crate could exist.
141 Some(format!("https://docs.rs/{}/*/", krate.display_name(db)?)))
142 .and_then(|s| Url::parse(&s).ok())
143}
144
145/// Get the filename and extension generated for a symbol by rustdoc.
146///
147/// Example: `struct.Shard.html`
148fn get_symbol_filename(db: &dyn HirDatabase, definition: &ModuleDef) -> Option<String> {
149 Some(match definition {
150 ModuleDef::Adt(adt) => match adt {
151 Adt::Struct(s) => format!("struct.{}.html", s.name(db)),
152 Adt::Enum(e) => format!("enum.{}.html", e.name(db)),
153 Adt::Union(u) => format!("union.{}.html", u.name(db)),
154 },
155 ModuleDef::Module(_) => "index.html".to_string(),
156 ModuleDef::Trait(t) => format!("trait.{}.html", t.name(db)),
157 ModuleDef::TypeAlias(t) => format!("type.{}.html", t.name(db)),
158 ModuleDef::BuiltinType(t) => format!("primitive.{}.html", t.as_name()),
159 ModuleDef::Function(f) => format!("fn.{}.html", f.name(db)),
160 ModuleDef::EnumVariant(ev) => {
161 format!("enum.{}.html#variant.{}", ev.parent_enum(db).name(db), ev.name(db))
162 }
163 ModuleDef::Const(c) => format!("const.{}.html", c.name(db)?),
164 ModuleDef::Static(s) => format!("static.{}.html", s.name(db)?),
165 })
166}
167
168struct IntraDocLink<'s> {
169 path: &'s str,
170 namespace: Option<Namespace>,
171}
172
173impl<'s> From<&'s str> for IntraDocLink<'s> {
174 fn from(s: &'s str) -> Self {
175 Self { path: strip_prefixes_suffixes(s), namespace: Namespace::from_intra_spec(s) }
176 }
177}
178
179#[derive(PartialEq, Eq, Hash, Copy, Clone, Debug)]
180enum Namespace {
181 Types,
182 Values,
183 Macros,
184}
185
186static TYPES: ([&str; 7], [&str; 0]) =
187 (["type", "struct", "enum", "mod", "trait", "union", "module"], []);
188static VALUES: ([&str; 8], [&str; 1]) =
189 (["value", "function", "fn", "method", "const", "static", "mod", "module"], ["()"]);
190static MACROS: ([&str; 1], [&str; 1]) = (["macro"], ["!"]);
191
192impl Namespace {
193 /// Extract the specified namespace from an intra-doc-link if one exists.
194 ///
195 /// # Examples
196 ///
197 /// * `struct MyStruct` -> `Namespace::Types`
198 /// * `panic!` -> `Namespace::Macros`
199 /// * `fn@from_intra_spec` -> `Namespace::Values`
200 fn from_intra_spec(s: &str) -> Option<Self> {
201 [
202 (Namespace::Types, (TYPES.0.iter(), TYPES.1.iter())),
203 (Namespace::Values, (VALUES.0.iter(), VALUES.1.iter())),
204 (Namespace::Macros, (MACROS.0.iter(), MACROS.1.iter())),
205 ]
206 .iter()
207 .filter(|(_ns, (prefixes, suffixes))| {
208 prefixes
209 .clone()
210 .map(|prefix| {
211 s.starts_with(*prefix)
212 && s.chars()
213 .nth(prefix.len() + 1)
214 .map(|c| c == '@' || c == ' ')
215 .unwrap_or(false)
216 })
217 .any(|cond| cond)
218 || suffixes
219 .clone()
220 .map(|suffix| {
221 s.starts_with(*suffix)
222 && s.chars()
223 .nth(suffix.len() + 1)
224 .map(|c| c == '@' || c == ' ')
225 .unwrap_or(false)
226 })
227 .any(|cond| cond)
228 })
229 .map(|(ns, (_, _))| *ns)
230 .next()
231 }
232}
233
234/// Sealed trait used solely for the generic bound on [`resolve_doc_link`].
235pub trait Resolvable {
236 fn resolver(&self, db: &dyn HirDatabase) -> Option<Resolver>;
237 fn try_into_module_def(self) -> Option<ModuleDef>;
238}
generated by cgit v1.2.3 (git 2.25.1) at 2024-09-08 17:50:28 +0100