1 //! Extracts, resolves and rewrites links and intra-doc links in markdown documentation.
6 use pulldown_cmark::{BrokenLink, CowStr, Event, InlineStr, LinkType, Options, Parser, Tag};
7 use pulldown_cmark_to_cmark::{cmark_with_options, Options as CMarkOptions};
11 use hir::{db::HirDatabase, Adt, AsAssocItem, AssocItem, AssocItemContainer, Crate, HasAttrs};
13 defs::{Definition, NameClass, NameRefClass},
14 helpers::pick_best_token,
18 ast::{self, IsString},
19 match_ast, AstNode, AstToken,
21 SyntaxNode, SyntaxToken, TextRange, TextSize, T,
25 doc_links::intra_doc_links::{parse_intra_doc_link, strip_prefixes_suffixes},
26 FilePosition, Semantics,
29 /// Weblink to an item's documentation.
30 pub(crate) type DocumentationLink = String;
32 const MARKDOWN_OPTIONS: Options =
33 Options::ENABLE_FOOTNOTES.union(Options::ENABLE_TABLES).union(Options::ENABLE_TASKLISTS);
35 /// Rewrite documentation links in markdown to point to an online host (e.g. docs.rs)
36 pub(crate) fn rewrite_links(db: &RootDatabase, markdown: &str, definition: Definition) -> String {
37 let mut cb = broken_link_clone_cb;
38 let doc = Parser::new_with_broken_link_callback(markdown, MARKDOWN_OPTIONS, Some(&mut cb));
40 let doc = map_links(doc, |target, title| {
41 // This check is imperfect, there's some overlap between valid intra-doc links
42 // and valid URLs so we choose to be too eager to try to resolve what might be
44 if target.contains("://") {
45 (target.to_string(), title.to_string())
48 // * path-based links: `../../module/struct.MyStruct.html`
49 // * module-based links (AKA intra-doc links): `super::super::module::MyStruct`
50 if let Some(rewritten) = rewrite_intra_doc_link(db, definition, target, title) {
53 if let Some(target) = rewrite_url_link(db, definition, target) {
54 return (target, title.to_string());
57 (target.to_string(), title.to_string())
60 let mut out = String::new();
65 CMarkOptions { code_block_token_count: 3, ..Default::default() },
71 /// Remove all links in markdown documentation.
72 pub(crate) fn remove_links(markdown: &str) -> String {
73 let mut drop_link = false;
75 let mut cb = |_: BrokenLink| {
76 let empty = InlineStr::try_from("").unwrap();
77 Some((CowStr::Inlined(empty), CowStr::Inlined(empty)))
79 let doc = Parser::new_with_broken_link_callback(markdown, MARKDOWN_OPTIONS, Some(&mut cb));
80 let doc = doc.filter_map(move |evt| match evt {
81 Event::Start(Tag::Link(link_type, target, title)) => {
82 if link_type == LinkType::Inline && target.contains("://") {
83 Some(Event::Start(Tag::Link(link_type, target, title)))
89 Event::End(_) if drop_link => {
96 let mut out = String::new();
101 CMarkOptions { code_block_token_count: 3, ..Default::default() },
107 /// Retrieve a link to documentation for the given symbol.
108 pub(crate) fn external_docs(
110 position: &FilePosition,
111 ) -> Option<DocumentationLink> {
112 let sema = &Semantics::new(db);
113 let file = sema.parse(position.file_id).syntax().clone();
114 let token = pick_best_token(file.token_at_offset(position.offset), |kind| match kind {
115 IDENT | INT_NUMBER | T![self] => 3,
116 T!['('] | T![')'] => 2,
117 kind if kind.is_trivia() => 0,
120 let token = sema.descend_into_macros_single(token);
122 let node = token.parent()?;
123 let definition = match_ast! {
125 ast::NameRef(name_ref) => match NameRefClass::classify(sema, &name_ref)? {
126 NameRefClass::Definition(def) => def,
127 NameRefClass::FieldShorthand { local_ref: _, field_ref } => {
128 Definition::Field(field_ref)
131 ast::Name(name) => match NameClass::classify(sema, &name)? {
132 NameClass::Definition(it) | NameClass::ConstReference(it) => it,
133 NameClass::PatFieldShorthand { local_def: _, field_ref } => Definition::Field(field_ref),
139 get_doc_link(db, definition)
142 /// Extracts all links from a given markdown text returning the definition text range, link-text
143 /// and the namespace if known.
144 pub(crate) fn extract_definitions_from_docs(
145 docs: &hir::Documentation,
146 ) -> Vec<(TextRange, String, Option<hir::Namespace>)> {
147 Parser::new_with_broken_link_callback(
150 Some(&mut broken_link_clone_cb),
153 .filter_map(|(event, range)| match event {
154 Event::Start(Tag::Link(_, target, _)) => {
155 let (link, ns) = parse_intra_doc_link(&target);
157 TextRange::new(range.start.try_into().ok()?, range.end.try_into().ok()?),
167 pub(crate) fn resolve_doc_path_for_def(
168 db: &dyn HirDatabase,
171 ns: Option<hir::Namespace>,
172 ) -> Option<Definition> {
173 let def = match def {
174 Definition::Module(it) => it.resolve_doc_path(db, link, ns),
175 Definition::Function(it) => it.resolve_doc_path(db, link, ns),
176 Definition::Adt(it) => it.resolve_doc_path(db, link, ns),
177 Definition::Variant(it) => it.resolve_doc_path(db, link, ns),
178 Definition::Const(it) => it.resolve_doc_path(db, link, ns),
179 Definition::Static(it) => it.resolve_doc_path(db, link, ns),
180 Definition::Trait(it) => it.resolve_doc_path(db, link, ns),
181 Definition::TypeAlias(it) => it.resolve_doc_path(db, link, ns),
182 Definition::Macro(it) => it.resolve_doc_path(db, link, ns),
183 Definition::Field(it) => it.resolve_doc_path(db, link, ns),
184 Definition::BuiltinAttr(_)
185 | Definition::ToolModule(_)
186 | Definition::BuiltinType(_)
187 | Definition::SelfType(_)
188 | Definition::Local(_)
189 | Definition::GenericParam(_)
190 | Definition::Label(_) => None,
193 Either::Left(def) => Some(Definition::from(def)),
194 Either::Right(def) => Some(Definition::Macro(def)),
198 pub(crate) fn doc_attributes(
199 sema: &Semantics<RootDatabase>,
201 ) -> Option<(hir::AttrsWithOwner, Definition)> {
204 ast::SourceFile(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Module(def))),
205 ast::Module(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Module(def))),
206 ast::Fn(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Function(def))),
207 ast::Struct(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Adt(hir::Adt::Struct(def)))),
208 ast::Union(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Adt(hir::Adt::Union(def)))),
209 ast::Enum(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Adt(hir::Adt::Enum(def)))),
210 ast::Variant(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Variant(def))),
211 ast::Trait(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Trait(def))),
212 ast::Static(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Static(def))),
213 ast::Const(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Const(def))),
214 ast::TypeAlias(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::TypeAlias(def))),
215 ast::Impl(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::SelfType(def))),
216 ast::RecordField(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Field(def))),
217 ast::TupleField(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Field(def))),
218 ast::Macro(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Macro(def))),
219 // ast::Use(it) => sema.to_def(&it).map(|def| (Box::new(it) as _, def.attrs(sema.db))),
225 pub(crate) struct DocCommentToken {
226 doc_token: SyntaxToken,
227 prefix_len: TextSize,
230 pub(crate) fn token_as_doc_comment(doc_token: &SyntaxToken) -> Option<DocCommentToken> {
233 ast::Comment(comment) => TextSize::try_from(comment.prefix().len()).ok(),
234 ast::String(string) => doc_token.ancestors().find_map(ast::Attr::cast)
235 .filter(|attr| attr.simple_name().as_deref() == Some("doc")).and_then(|_| string.open_quote_text_range().map(|it| it.len())),
238 }).map(|prefix_len| DocCommentToken { prefix_len, doc_token: doc_token.clone() })
241 impl DocCommentToken {
242 pub(crate) fn get_definition_with_descend_at<T>(
244 sema: &Semantics<RootDatabase>,
246 // Definition, CommentOwner, range of intra doc link in original file
247 mut cb: impl FnMut(Definition, SyntaxNode, TextRange) -> Option<T>,
249 let DocCommentToken { prefix_len, doc_token } = self;
250 // offset relative to the comments contents
251 let original_start = doc_token.text_range().start();
252 let relative_comment_offset = offset - original_start - prefix_len;
254 sema.descend_into_macros(doc_token).into_iter().find_map(|t| {
255 let (node, descended_prefix_len) = match_ast! {
257 ast::Comment(comment) => (t.parent()?, TextSize::try_from(comment.prefix().len()).ok()?),
258 ast::String(string) => (t.ancestors().skip_while(|n| n.kind() != ATTR).nth(1)?, string.open_quote_text_range()?.len()),
262 let token_start = t.text_range().start();
263 let abs_in_expansion_offset = token_start + relative_comment_offset + descended_prefix_len;
265 let (attributes, def) = doc_attributes(sema, &node)?;
266 let (docs, doc_mapping) = attributes.docs_with_rangemap(sema.db)?;
267 let (in_expansion_range, link, ns) =
268 extract_definitions_from_docs(&docs).into_iter().find_map(|(range, link, ns)| {
269 let mapped = doc_mapping.map(range)?;
270 (mapped.value.contains(abs_in_expansion_offset)).then(|| (mapped.value, link, ns))
272 // get the relative range to the doc/attribute in the expansion
273 let in_expansion_relative_range = in_expansion_range - descended_prefix_len - token_start;
274 // Apply relative range to the original input comment
275 let absolute_range = in_expansion_relative_range + original_start + prefix_len;
276 let def = resolve_doc_path_for_def(sema.db, def, &link, ns)?;
277 cb(def, node, absolute_range)
282 fn broken_link_clone_cb<'a, 'b>(link: BrokenLink<'a>) -> Option<(CowStr<'b>, CowStr<'b>)> {
283 // These allocations are actually unnecessary but the lifetimes on BrokenLinkCallback are wrong
284 // this is fixed in the repo but not on the crates.io release yet
286 /*url*/ link.reference.to_owned().into(),
287 /*title*/ link.reference.to_owned().into(),
292 // BUG: For Option::Some
293 // Returns https://doc.rust-lang.org/nightly/core/prelude/v1/enum.Option.html#variant.Some
294 // Instead of https://doc.rust-lang.org/nightly/core/option/enum.Option.html
296 // This should cease to be a problem if RFC2988 (Stable Rustdoc URLs) is implemented
297 // https://github.com/rust-lang/rfcs/pull/2988
298 fn get_doc_link(db: &RootDatabase, def: Definition) -> Option<String> {
299 let (target, file, frag) = filename_and_frag_for_def(db, def)?;
301 let krate = crate_of_def(db, target)?;
302 let mut url = get_doc_base_url(db, &krate)?;
304 if let Some(path) = mod_path_of_def(db, target) {
305 url = url.join(&path).ok()?;
308 url = url.join(&file).ok()?;
309 url.set_fragment(frag.as_deref());
314 fn rewrite_intra_doc_link(
319 ) -> Option<(String, String)> {
320 let (link, ns) = parse_intra_doc_link(target);
322 let resolved = resolve_doc_path_for_def(db, def, link, ns)?;
323 let krate = crate_of_def(db, resolved)?;
324 let mut url = get_doc_base_url(db, &krate)?;
326 let (_, file, frag) = filename_and_frag_for_def(db, resolved)?;
327 if let Some(path) = mod_path_of_def(db, resolved) {
328 url = url.join(&path).ok()?;
331 url = url.join(&file).ok()?;
332 url.set_fragment(frag.as_deref());
334 Some((url.into(), strip_prefixes_suffixes(title).to_string()))
337 /// Try to resolve path to local documentation via path-based links (i.e. `../gateway/struct.Shard.html`).
338 fn rewrite_url_link(db: &RootDatabase, def: Definition, target: &str) -> Option<String> {
339 if !(target.contains('#') || target.contains(".html")) {
343 let krate = crate_of_def(db, def)?;
344 let mut url = get_doc_base_url(db, &krate)?;
345 let (def, file, frag) = filename_and_frag_for_def(db, def)?;
347 if let Some(path) = mod_path_of_def(db, def) {
348 url = url.join(&path).ok()?;
351 url = url.join(&file).ok()?;
352 url.set_fragment(frag.as_deref());
353 url.join(target).ok().map(Into::into)
356 fn crate_of_def(db: &RootDatabase, def: Definition) -> Option<Crate> {
357 let krate = match def {
358 // Definition::module gives back the parent module, we don't want that as it fails for root modules
359 Definition::Module(module) => module.krate(),
360 def => def.module(db)?.krate(),
365 fn mod_path_of_def(db: &RootDatabase, def: Definition) -> Option<String> {
366 def.canonical_module_path(db).map(|it| {
367 let mut path = String::new();
368 it.flat_map(|it| it.name(db)).for_each(|name| format_to!(path, "{}/", name));
373 /// Rewrites a markdown document, applying 'callback' to each link.
375 events: impl Iterator<Item = Event<'e>>,
376 callback: impl Fn(&str, &str) -> (String, String),
377 ) -> impl Iterator<Item = Event<'e>> {
378 let mut in_link = false;
379 let mut link_target: Option<CowStr> = None;
381 events.map(move |evt| match evt {
382 Event::Start(Tag::Link(_, ref target, _)) => {
384 link_target = Some(target.clone());
387 Event::End(Tag::Link(link_type, target, _)) => {
389 Event::End(Tag::Link(
391 link_target.take().unwrap_or(target),
392 CowStr::Borrowed(""),
395 Event::Text(s) if in_link => {
396 let (link_target_s, link_name) = callback(&link_target.take().unwrap(), &s);
397 link_target = Some(CowStr::Boxed(link_target_s.into()));
398 Event::Text(CowStr::Boxed(link_name.into()))
400 Event::Code(s) if in_link => {
401 let (link_target_s, link_name) = callback(&link_target.take().unwrap(), &s);
402 link_target = Some(CowStr::Boxed(link_target_s.into()));
403 Event::Code(CowStr::Boxed(link_name.into()))
409 /// Get the root URL for the documentation of a crate.
412 /// https://doc.rust-lang.org/std/iter/trait.Iterator.html#tymethod.next
413 /// ^^^^^^^^^^^^^^^^^^^^^^^^^^
415 fn get_doc_base_url(db: &RootDatabase, krate: &Crate) -> Option<Url> {
416 let display_name = krate.display_name(db)?;
417 let base = match &**display_name.crate_name() {
418 // std and co do not specify `html_root_url` any longer so we gotta handwrite this ourself.
419 // FIXME: Use the toolchains channel instead of nightly
420 name @ ("core" | "std" | "alloc" | "proc_macro" | "test") => {
421 format!("https://doc.rust-lang.org/nightly/{}", name)
424 krate.get_html_root_url(db).or_else(|| {
425 let version = krate.version(db);
426 // Fallback to docs.rs. This uses `display_name` and can never be
427 // correct, but that's what fallbacks are about.
429 // FIXME: clicking on the link should just open the file in the editor,
430 // instead of falling back to external urls.
432 "https://docs.rs/{krate}/{version}/",
433 krate = display_name,
434 version = version.as_deref().unwrap_or("*")
439 Url::parse(&base).ok()?.join(&format!("{}/", display_name)).ok()
442 /// Get the filename and extension generated for a symbol by rustdoc.
445 /// https://doc.rust-lang.org/std/iter/trait.Iterator.html#tymethod.next
446 /// ^^^^^^^^^^^^^^^^^^^
448 fn filename_and_frag_for_def(
449 db: &dyn HirDatabase,
451 ) -> Option<(Definition, String, Option<String>)> {
452 if let Some(assoc_item) = def.as_assoc_item(db) {
453 let def = match assoc_item.container(db) {
454 AssocItemContainer::Trait(t) => t.into(),
455 AssocItemContainer::Impl(i) => i.self_ty(db).as_adt()?.into(),
457 let (_, file, _) = filename_and_frag_for_def(db, def)?;
458 let frag = get_assoc_item_fragment(db, assoc_item)?;
459 return Some((def, file, Some(frag)));
462 let res = match def {
463 Definition::Adt(adt) => match adt {
464 Adt::Struct(s) => format!("struct.{}.html", s.name(db)),
465 Adt::Enum(e) => format!("enum.{}.html", e.name(db)),
466 Adt::Union(u) => format!("union.{}.html", u.name(db)),
468 Definition::Module(m) => match m.name(db) {
469 Some(name) => format!("{}/index.html", name),
470 None => String::from("index.html"),
472 Definition::Trait(t) => format!("trait.{}.html", t.name(db)),
473 Definition::TypeAlias(t) => format!("type.{}.html", t.name(db)),
474 Definition::BuiltinType(t) => format!("primitive.{}.html", t.name()),
475 Definition::Function(f) => format!("fn.{}.html", f.name(db)),
476 Definition::Variant(ev) => {
477 format!("enum.{}.html#variant.{}", ev.parent_enum(db).name(db), ev.name(db))
479 Definition::Const(c) => format!("const.{}.html", c.name(db)?),
480 Definition::Static(s) => format!("static.{}.html", s.name(db)),
481 Definition::Macro(mac) => format!("macro.{}.html", mac.name(db)?),
482 Definition::Field(field) => {
483 let def = match field.parent_def(db) {
484 hir::VariantDef::Struct(it) => Definition::Adt(it.into()),
485 hir::VariantDef::Union(it) => Definition::Adt(it.into()),
486 hir::VariantDef::Variant(it) => Definition::Variant(it),
488 let (_, file, _) = filename_and_frag_for_def(db, def)?;
489 return Some((def, file, Some(format!("structfield.{}", field.name(db)))));
491 Definition::SelfType(impl_) => {
492 let adt = impl_.self_ty(db).as_adt()?.into();
493 let (_, file, _) = filename_and_frag_for_def(db, adt)?;
494 // FIXME fragment numbering
495 return Some((adt, file, Some(String::from("impl"))));
498 | Definition::GenericParam(_)
499 | Definition::Label(_)
500 | Definition::BuiltinAttr(_)
501 | Definition::ToolModule(_) => return None,
504 Some((def, res, None))
507 /// Get the fragment required to link to a specific field, method, associated type, or associated constant.
510 /// https://doc.rust-lang.org/std/iter/trait.Iterator.html#tymethod.next
513 fn get_assoc_item_fragment(db: &dyn HirDatabase, assoc_item: hir::AssocItem) -> Option<String> {
514 Some(match assoc_item {
515 AssocItem::Function(function) => {
516 let is_trait_method =
517 function.as_assoc_item(db).and_then(|assoc| assoc.containing_trait(db)).is_some();
518 // This distinction may get more complicated when specialization is available.
519 // Rustdoc makes this decision based on whether a method 'has defaultness'.
520 // Currently this is only the case for provided trait methods.
521 if is_trait_method && !function.has_body(db) {
522 format!("tymethod.{}", function.name(db))
524 format!("method.{}", function.name(db))
527 AssocItem::Const(constant) => format!("associatedconstant.{}", constant.name(db)?),
528 AssocItem::TypeAlias(ty) => format!("associatedtype.{}", ty.name(db)),
534 use expect_test::{expect, Expect};
535 use ide_db::base_db::FileRange;
536 use itertools::Itertools;
538 use crate::{fixture, TryToNav};
543 fn external_docs_doc_url_crate() {
546 //- /main.rs crate:main deps:foo
548 //- /lib.rs crate:foo
551 expect![[r#"https://docs.rs/foo/*/foo/index.html"#]],
556 fn external_docs_doc_url_std_crate() {
559 //- /main.rs crate:std
562 expect![[r#"https://doc.rust-lang.org/nightly/std/index.html"#]],
567 fn external_docs_doc_url_struct() {
570 //- /main.rs crate:foo
573 expect![[r#"https://docs.rs/foo/*/foo/struct.Foo.html"#]],
578 fn external_docs_doc_url_struct_field() {
581 //- /main.rs crate:foo
586 expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#structfield.field"##]],
591 fn external_docs_doc_url_fn() {
594 //- /main.rs crate:foo
597 expect![[r#"https://docs.rs/foo/*/foo/fn.foo.html"#]],
602 fn external_docs_doc_url_impl_assoc() {
605 //- /main.rs crate:foo
611 expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#method.method"##]],
615 //- /main.rs crate:foo
618 const CONST$0: () = ();
621 expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#associatedconstant.CONST"##]],
626 fn external_docs_doc_url_impl_trait_assoc() {
629 //- /main.rs crate:foo
638 expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#method.method"##]],
642 //- /main.rs crate:foo
645 const CONST: () = ();
648 const CONST$0: () = ();
651 expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#associatedconstant.CONST"##]],
655 //- /main.rs crate:foo
664 expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#associatedtype.Type"##]],
669 fn external_docs_doc_url_trait_assoc() {
672 //- /main.rs crate:foo
677 expect![[r##"https://docs.rs/foo/*/foo/trait.Foo.html#tymethod.method"##]],
681 //- /main.rs crate:foo
686 expect![[r##"https://docs.rs/foo/*/foo/trait.Foo.html#associatedconstant.CONST"##]],
690 //- /main.rs crate:foo
695 expect![[r##"https://docs.rs/foo/*/foo/trait.Foo.html#associatedtype.Type"##]],
700 fn external_docs_trait() {
703 //- /main.rs crate:foo
706 expect![[r#"https://docs.rs/foo/*/foo/trait.Trait.html"#]],
711 fn external_docs_module() {
714 //- /main.rs crate:foo
719 expect![[r#"https://docs.rs/foo/*/foo/foo/bar/index.html"#]],
724 fn external_docs_reexport_order() {
727 //- /main.rs crate:foo
729 pub use module::Item;
737 let bar: wrapper::It$0em;
740 expect![[r#"https://docs.rs/foo/*/foo/wrapper/module/struct.Item.html"#]],
745 fn test_trait_items() {
757 // ^^^^^ Trait::CONST
766 fn rewrite_html_root_url() {
769 //- /main.rs crate:foo
770 #![doc(arbitrary_attribute = "test", html_root_url = "https:/example.com", arbitrary_attribute2)]
778 expect![[r#"[Foo](https://example.com/foo/foo/struct.Foo.html)"#]],
783 fn rewrite_on_field() {
786 //- /main.rs crate:foo
788 /// [Foo](struct.Foo.html)
792 expect![[r#"[Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]],
797 fn rewrite_struct() {
800 //- /main.rs crate:foo
804 expect![[r#"[Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]],
808 //- /main.rs crate:foo
812 expect![[r#"[`Foo`](https://docs.rs/foo/*/foo/struct.Foo.html)"#]],
816 //- /main.rs crate:foo
817 /// [Foo](struct.Foo.html)
820 expect![[r#"[Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]],
824 //- /main.rs crate:foo
825 /// [struct Foo](struct.Foo.html)
828 expect![[r#"[struct Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]],
832 //- /main.rs crate:foo
838 expect![[r#"[my Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]],
842 fn check_external_docs(ra_fixture: &str, expect: Expect) {
843 let (analysis, position) = fixture::position(ra_fixture);
844 let url = analysis.external_docs(position).unwrap().expect("could not find url for symbol");
846 expect.assert_eq(&url)
849 fn check_rewrite(ra_fixture: &str, expect: Expect) {
850 let (analysis, position) = fixture::position(ra_fixture);
851 let sema = &Semantics::new(&*analysis.db);
852 let (cursor_def, docs) = def_under_cursor(sema, &position);
853 let res = rewrite_links(sema.db, docs.as_str(), cursor_def);
854 expect.assert_eq(&res)
857 fn check_doc_links(ra_fixture: &str) {
858 let key_fn = |&(FileRange { file_id, range }, _): &_| (file_id, range.start());
860 let (analysis, position, mut expected) = fixture::annotations(ra_fixture);
861 expected.sort_by_key(key_fn);
862 let sema = &Semantics::new(&*analysis.db);
863 let (cursor_def, docs) = def_under_cursor(sema, &position);
864 let defs = extract_definitions_from_docs(&docs);
865 let actual: Vec<_> = defs
867 .map(|(_, link, ns)| {
868 let def = resolve_doc_path_for_def(sema.db, cursor_def, &link, ns)
869 .unwrap_or_else(|| panic!("Failed to resolve {}", link));
870 let nav_target = def.try_to_nav(sema.db).unwrap();
871 let range = FileRange {
872 file_id: nav_target.file_id,
873 range: nav_target.focus_or_full_range(),
877 .sorted_by_key(key_fn)
879 assert_eq!(expected, actual);
883 sema: &Semantics<RootDatabase>,
884 position: &FilePosition,
885 ) -> (Definition, hir::Documentation) {
886 let (docs, def) = sema
887 .parse(position.file_id)
889 .token_at_offset(position.offset)
893 .find_map(|it| node_to_def(sema, &it))
894 .expect("no def found")
896 let docs = docs.expect("no docs found for cursor def");
901 sema: &Semantics<RootDatabase>,
903 ) -> Option<Option<(Option<hir::Documentation>, Definition)>> {
906 ast::SourceFile(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Module(def))),
907 ast::Module(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Module(def))),
908 ast::Fn(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Function(def))),
909 ast::Struct(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Adt(hir::Adt::Struct(def)))),
910 ast::Union(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Adt(hir::Adt::Union(def)))),
911 ast::Enum(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Adt(hir::Adt::Enum(def)))),
912 ast::Variant(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Variant(def))),
913 ast::Trait(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Trait(def))),
914 ast::Static(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Static(def))),
915 ast::Const(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Const(def))),
916 ast::TypeAlias(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::TypeAlias(def))),
917 ast::Impl(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::SelfType(def))),
918 ast::RecordField(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Field(def))),
919 ast::TupleField(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Field(def))),
920 ast::Macro(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Macro(def))),
921 // ast::Use(it) => sema.to_def(&it).map(|def| (Box::new(it) as _, def.attrs(sema.db))),