X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=crates%2Fide%2Fsrc%2Fdoc_links.rs;h=a78358f20fd9e3e3aac75be0ca38944da280471c;hb=c6f776c5f9aa7d850be24d0288700905e833dc9e;hp=617f63d358283e99bfd50d906a3f121a8b8a00be;hpb=bf7622614895ec6cbed7ea5a6b6b2616680fe50f;p=rust.git diff --git a/crates/ide/src/doc_links.rs b/crates/ide/src/doc_links.rs index 617f63d3582..a78358f20fd 100644 --- a/crates/ide/src/doc_links.rs +++ b/crates/ide/src/doc_links.rs @@ -1,15 +1,18 @@ //! Extracts, resolves and rewrites links and intra-doc links in markdown documentation. +#[cfg(test)] +mod tests; + mod intra_doc_links; -use either::Either; use pulldown_cmark::{BrokenLink, CowStr, Event, InlineStr, LinkType, Options, Parser, Tag}; -use pulldown_cmark_to_cmark::{cmark_with_options, Options as CMarkOptions}; +use pulldown_cmark_to_cmark::{cmark_resume_with_options, Options as CMarkOptions}; use stdx::format_to; use url::Url; -use hir::{db::HirDatabase, Adt, AsAssocItem, AssocItem, AssocItemContainer, Crate, HasAttrs}; +use hir::{db::HirDatabase, Adt, AsAssocItem, AssocItem, AssocItemContainer, HasAttrs}; use ide_db::{ + base_db::{CrateOrigin, LangCrateOrigin, SourceDatabase}, defs::{Definition, NameClass, NameRefClass}, helpers::pick_best_token, RootDatabase, @@ -42,27 +45,27 @@ pub(crate) fn rewrite_links(db: &RootDatabase, markdown: &str, definition: Defin // and valid URLs so we choose to be too eager to try to resolve what might be // a URL. if target.contains("://") { - (target.to_string(), title.to_string()) + (Some(LinkType::Inline), target.to_string(), title.to_string()) } else { // Two possibilities: // * path-based links: `../../module/struct.MyStruct.html` // * module-based links (AKA intra-doc links): `super::super::module::MyStruct` - if let Some(rewritten) = rewrite_intra_doc_link(db, definition, target, title) { - return rewritten; + if let Some((target, title)) = rewrite_intra_doc_link(db, definition, target, title) { + return (None, target, title); } if let Some(target) = rewrite_url_link(db, definition, target) { - return (target, title.to_string()); + return (Some(LinkType::Inline), target, title.to_string()); } - (target.to_string(), title.to_string()) + (None, target.to_string(), title.to_string()) } }); let mut out = String::new(); - cmark_with_options( + cmark_resume_with_options( doc, &mut out, None, - CMarkOptions { code_block_backticks: 3, ..Default::default() }, + CMarkOptions { code_block_token_count: 3, ..Default::default() }, ) .ok(); out @@ -94,11 +97,11 @@ pub(crate) fn remove_links(markdown: &str) -> String { }); let mut out = String::new(); - cmark_with_options( + cmark_resume_with_options( doc, &mut out, None, - CMarkOptions { code_block_backticks: 3, ..Default::default() }, + CMarkOptions { code_block_token_count: 3, ..Default::default() }, ) .ok(); out @@ -170,7 +173,7 @@ pub(crate) fn resolve_doc_path_for_def( link: &str, ns: Option, ) -> Option { - let def = match def { + match def { Definition::Module(it) => it.resolve_doc_path(db, link, ns), Definition::Function(it) => it.resolve_doc_path(db, link, ns), Definition::Adt(it) => it.resolve_doc_path(db, link, ns), @@ -188,11 +191,8 @@ pub(crate) fn resolve_doc_path_for_def( | Definition::Local(_) | Definition::GenericParam(_) | Definition::Label(_) => None, - }?; - match def { - Either::Left(def) => Some(Definition::from(def)), - Either::Right(def) => Some(Definition::Macro(def)), } + .map(Definition::from) } pub(crate) fn doc_attributes( @@ -231,7 +231,7 @@ pub(crate) fn token_as_doc_comment(doc_token: &SyntaxToken) -> Option TextSize::try_from(comment.prefix().len()).ok(), - ast::String(string) => doc_token.ancestors().find_map(ast::Attr::cast) + ast::String(string) => doc_token.parent_ancestors().find_map(ast::Attr::cast) .filter(|attr| attr.simple_name().as_deref() == Some("doc")).and_then(|_| string.open_quote_text_range().map(|it| it.len())), _ => None, } @@ -255,7 +255,7 @@ pub(crate) fn get_definition_with_descend_at( let (node, descended_prefix_len) = match_ast! { match t { ast::Comment(comment) => (t.parent()?, TextSize::try_from(comment.prefix().len()).ok()?), - ast::String(string) => (t.ancestors().skip_while(|n| n.kind() != ATTR).nth(1)?, string.open_quote_text_range()?.len()), + ast::String(string) => (t.parent_ancestors().skip_while(|n| n.kind() != ATTR).nth(1)?, string.open_quote_text_range()?.len()), _ => return None, } }; @@ -279,13 +279,8 @@ pub(crate) fn get_definition_with_descend_at( } } -fn broken_link_clone_cb<'a, 'b>(link: BrokenLink<'a>) -> Option<(CowStr<'b>, CowStr<'b>)> { - // These allocations are actually unnecessary but the lifetimes on BrokenLinkCallback are wrong - // this is fixed in the repo but not on the crates.io release yet - Some(( - /*url*/ link.reference.to_owned().into(), - /*title*/ link.reference.to_owned().into(), - )) +fn broken_link_clone_cb<'a>(link: BrokenLink<'a>) -> Option<(CowStr<'a>, CowStr<'a>)> { + Some((/*url*/ link.reference.clone(), /*title*/ link.reference)) } // FIXME: @@ -298,8 +293,7 @@ fn broken_link_clone_cb<'a, 'b>(link: BrokenLink<'a>) -> Option<(CowStr<'b>, Cow fn get_doc_link(db: &RootDatabase, def: Definition) -> Option { let (target, file, frag) = filename_and_frag_for_def(db, def)?; - let krate = crate_of_def(db, target)?; - let mut url = get_doc_base_url(db, &krate)?; + let mut url = get_doc_base_url(db, target)?; if let Some(path) = mod_path_of_def(db, target) { url = url.join(&path).ok()?; @@ -320,8 +314,7 @@ fn rewrite_intra_doc_link( let (link, ns) = parse_intra_doc_link(target); let resolved = resolve_doc_path_for_def(db, def, link, ns)?; - let krate = crate_of_def(db, resolved)?; - let mut url = get_doc_base_url(db, &krate)?; + let mut url = get_doc_base_url(db, resolved)?; let (_, file, frag) = filename_and_frag_for_def(db, resolved)?; if let Some(path) = mod_path_of_def(db, resolved) { @@ -340,8 +333,7 @@ fn rewrite_url_link(db: &RootDatabase, def: Definition, target: &str) -> Option< return None; } - let krate = crate_of_def(db, def)?; - let mut url = get_doc_base_url(db, &krate)?; + let mut url = get_doc_base_url(db, def)?; let (def, file, frag) = filename_and_frag_for_def(db, def)?; if let Some(path) = mod_path_of_def(db, def) { @@ -353,15 +345,6 @@ fn rewrite_url_link(db: &RootDatabase, def: Definition, target: &str) -> Option< url.join(target).ok().map(Into::into) } -fn crate_of_def(db: &RootDatabase, def: Definition) -> Option { - let krate = match def { - // Definition::module gives back the parent module, we don't want that as it fails for root modules - Definition::Module(module) => module.krate(), - def => def.module(db)?.krate(), - }; - Some(krate) -} - fn mod_path_of_def(db: &RootDatabase, def: Definition) -> Option { def.canonical_module_path(db).map(|it| { let mut path = String::new(); @@ -373,52 +356,72 @@ fn mod_path_of_def(db: &RootDatabase, def: Definition) -> Option { /// Rewrites a markdown document, applying 'callback' to each link. fn map_links<'e>( events: impl Iterator>, - callback: impl Fn(&str, &str) -> (String, String), + callback: impl Fn(&str, &str) -> (Option, String, String), ) -> impl Iterator> { let mut in_link = false; - let mut link_target: Option = None; + // holds the origin link target on start event and the rewritten one on end event + let mut end_link_target: Option = None; + // normally link's type is determined by the type of link tag in the end event, + // however in some cases we want to change the link type, for example, + // `Shortcut` type doesn't make sense for url links + let mut end_link_type: Option = None; events.map(move |evt| match evt { - Event::Start(Tag::Link(_, ref target, _)) => { + Event::Start(Tag::Link(link_type, ref target, _)) => { in_link = true; - link_target = Some(target.clone()); + end_link_target = Some(target.clone()); + end_link_type = Some(link_type); evt } Event::End(Tag::Link(link_type, target, _)) => { in_link = false; Event::End(Tag::Link( - link_type, - link_target.take().unwrap_or(target), + end_link_type.unwrap_or(link_type), + end_link_target.take().unwrap_or(target), CowStr::Borrowed(""), )) } Event::Text(s) if in_link => { - let (link_target_s, link_name) = callback(&link_target.take().unwrap(), &s); - link_target = Some(CowStr::Boxed(link_target_s.into())); + let (_, link_target_s, link_name) = callback(&end_link_target.take().unwrap(), &s); + end_link_target = Some(CowStr::Boxed(link_target_s.into())); Event::Text(CowStr::Boxed(link_name.into())) } Event::Code(s) if in_link => { - let (link_target_s, link_name) = callback(&link_target.take().unwrap(), &s); - link_target = Some(CowStr::Boxed(link_target_s.into())); + let (_, link_target_s, link_name) = callback(&end_link_target.take().unwrap(), &s); + end_link_target = Some(CowStr::Boxed(link_target_s.into())); Event::Code(CowStr::Boxed(link_name.into())) } _ => evt, }) } -/// Get the root URL for the documentation of a crate. +/// Get the root URL for the documentation of a definition. /// /// ```ignore /// https://doc.rust-lang.org/std/iter/trait.Iterator.html#tymethod.next /// ^^^^^^^^^^^^^^^^^^^^^^^^^^ /// ``` -fn get_doc_base_url(db: &RootDatabase, krate: &Crate) -> Option { +fn get_doc_base_url(db: &RootDatabase, def: Definition) -> Option { + // special case base url of `BuiltinType` to core + // https://github.com/rust-lang/rust-analyzer/issues/12250 + if let Definition::BuiltinType(..) = def { + return Url::parse("https://doc.rust-lang.org/nightly/core/").ok(); + }; + + let krate = def.krate(db)?; let display_name = krate.display_name(db)?; - let base = match &**display_name.crate_name() { + + let base = match db.crate_graph()[krate.into()].origin { // std and co do not specify `html_root_url` any longer so we gotta handwrite this ourself. // FIXME: Use the toolchains channel instead of nightly - name @ ("core" | "std" | "alloc" | "proc_macro" | "test") => { - format!("https://doc.rust-lang.org/nightly/{}", name) + CrateOrigin::Lang( + origin @ (LangCrateOrigin::Alloc + | LangCrateOrigin::Core + | LangCrateOrigin::ProcMacro + | LangCrateOrigin::Std + | LangCrateOrigin::Test), + ) => { + format!("https://doc.rust-lang.org/nightly/{origin}") } _ => { krate.get_html_root_url(db).or_else(|| { @@ -466,7 +469,13 @@ fn filename_and_frag_for_def( Adt::Union(u) => format!("union.{}.html", u.name(db)), }, Definition::Module(m) => match m.name(db) { - Some(name) => format!("{}/index.html", name), + // `#[doc(keyword = "...")]` is internal used only by rust compiler + Some(name) => match m.attrs(db).by_key("doc").find_string_value_in_tt("keyword") { + Some(kw) => { + format!("keyword.{}.html", kw.trim_matches('"')) + } + None => format!("{}/index.html", name), + }, None => String::from("index.html"), }, Definition::Trait(t) => format!("trait.{}.html", t.name(db)), @@ -478,7 +487,7 @@ fn filename_and_frag_for_def( } Definition::Const(c) => format!("const.{}.html", c.name(db)?), Definition::Static(s) => format!("static.{}.html", s.name(db)), - Definition::Macro(mac) => format!("macro.{}.html", mac.name(db)?), + Definition::Macro(mac) => format!("macro.{}.html", mac.name(db)), Definition::Field(field) => { let def = match field.parent_def(db) { hir::VariantDef::Struct(it) => Definition::Adt(it.into()), @@ -528,399 +537,3 @@ fn get_assoc_item_fragment(db: &dyn HirDatabase, assoc_item: hir::AssocItem) -> AssocItem::TypeAlias(ty) => format!("associatedtype.{}", ty.name(db)), }) } - -#[cfg(test)] -mod tests { - use expect_test::{expect, Expect}; - use ide_db::base_db::FileRange; - use itertools::Itertools; - - use crate::{fixture, TryToNav}; - - use super::*; - - #[test] - fn external_docs_doc_url_crate() { - check_external_docs( - r#" -//- /main.rs crate:main deps:foo -use foo$0::Foo; -//- /lib.rs crate:foo -pub struct Foo; -"#, - expect![[r#"https://docs.rs/foo/*/foo/index.html"#]], - ); - } - - #[test] - fn external_docs_doc_url_std_crate() { - check_external_docs( - r#" -//- /main.rs crate:std -use self$0; -"#, - expect![[r#"https://doc.rust-lang.org/nightly/std/index.html"#]], - ); - } - - #[test] - fn external_docs_doc_url_struct() { - check_external_docs( - r#" -//- /main.rs crate:foo -pub struct Fo$0o; -"#, - expect![[r#"https://docs.rs/foo/*/foo/struct.Foo.html"#]], - ); - } - - #[test] - fn external_docs_doc_url_struct_field() { - check_external_docs( - r#" -//- /main.rs crate:foo -pub struct Foo { - field$0: () -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#structfield.field"##]], - ); - } - - #[test] - fn external_docs_doc_url_fn() { - check_external_docs( - r#" -//- /main.rs crate:foo -pub fn fo$0o() {} -"#, - expect![[r#"https://docs.rs/foo/*/foo/fn.foo.html"#]], - ); - } - - #[test] - fn external_docs_doc_url_impl_assoc() { - check_external_docs( - r#" -//- /main.rs crate:foo -pub struct Foo; -impl Foo { - pub fn method$0() {} -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#method.method"##]], - ); - check_external_docs( - r#" -//- /main.rs crate:foo -pub struct Foo; -impl Foo { - const CONST$0: () = (); -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#associatedconstant.CONST"##]], - ); - } - - #[test] - fn external_docs_doc_url_impl_trait_assoc() { - check_external_docs( - r#" -//- /main.rs crate:foo -pub struct Foo; -pub trait Trait { - fn method() {} -} -impl Trait for Foo { - pub fn method$0() {} -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#method.method"##]], - ); - check_external_docs( - r#" -//- /main.rs crate:foo -pub struct Foo; -pub trait Trait { - const CONST: () = (); -} -impl Trait for Foo { - const CONST$0: () = (); -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#associatedconstant.CONST"##]], - ); - check_external_docs( - r#" -//- /main.rs crate:foo -pub struct Foo; -pub trait Trait { - type Type; -} -impl Trait for Foo { - type Type$0 = (); -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/struct.Foo.html#associatedtype.Type"##]], - ); - } - - #[test] - fn external_docs_doc_url_trait_assoc() { - check_external_docs( - r#" -//- /main.rs crate:foo -pub trait Foo { - fn method$0(); -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/trait.Foo.html#tymethod.method"##]], - ); - check_external_docs( - r#" -//- /main.rs crate:foo -pub trait Foo { - const CONST$0: (); -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/trait.Foo.html#associatedconstant.CONST"##]], - ); - check_external_docs( - r#" -//- /main.rs crate:foo -pub trait Foo { - type Type$0; -} -"#, - expect![[r##"https://docs.rs/foo/*/foo/trait.Foo.html#associatedtype.Type"##]], - ); - } - - #[test] - fn external_docs_trait() { - check_external_docs( - r#" -//- /main.rs crate:foo -trait Trait$0 {} -"#, - expect![[r#"https://docs.rs/foo/*/foo/trait.Trait.html"#]], - ) - } - - #[test] - fn external_docs_module() { - check_external_docs( - r#" -//- /main.rs crate:foo -pub mod foo { - pub mod ba$0r {} -} -"#, - expect![[r#"https://docs.rs/foo/*/foo/foo/bar/index.html"#]], - ) - } - - #[test] - fn external_docs_reexport_order() { - check_external_docs( - r#" -//- /main.rs crate:foo -pub mod wrapper { - pub use module::Item; - - pub mod module { - pub struct Item; - } -} - -fn foo() { - let bar: wrapper::It$0em; -} - "#, - expect![[r#"https://docs.rs/foo/*/foo/wrapper/module/struct.Item.html"#]], - ) - } - - #[test] - fn test_trait_items() { - check_doc_links( - r#" -/// [`Trait`] -/// [`Trait::Type`] -/// [`Trait::CONST`] -/// [`Trait::func`] -trait Trait$0 { - // ^^^^^ Trait - type Type; - // ^^^^ Trait::Type - const CONST: usize; - // ^^^^^ Trait::CONST - fn func(); - // ^^^^ Trait::func -} - "#, - ) - } - - #[test] - fn rewrite_html_root_url() { - check_rewrite( - r#" -//- /main.rs crate:foo -#![doc(arbitrary_attribute = "test", html_root_url = "https:/example.com", arbitrary_attribute2)] - -pub mod foo { - pub struct Foo; -} -/// [Foo](foo::Foo) -pub struct B$0ar -"#, - expect![[r#"[Foo](https://example.com/foo/foo/struct.Foo.html)"#]], - ); - } - - #[test] - fn rewrite_on_field() { - check_rewrite( - r#" -//- /main.rs crate:foo -pub struct Foo { - /// [Foo](struct.Foo.html) - fie$0ld: () -} -"#, - expect![[r#"[Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]], - ); - } - - #[test] - fn rewrite_struct() { - check_rewrite( - r#" -//- /main.rs crate:foo -/// [Foo] -pub struct $0Foo; -"#, - expect![[r#"[Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]], - ); - check_rewrite( - r#" -//- /main.rs crate:foo -/// [`Foo`] -pub struct $0Foo; -"#, - expect![[r#"[`Foo`](https://docs.rs/foo/*/foo/struct.Foo.html)"#]], - ); - check_rewrite( - r#" -//- /main.rs crate:foo -/// [Foo](struct.Foo.html) -pub struct $0Foo; -"#, - expect![[r#"[Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]], - ); - check_rewrite( - r#" -//- /main.rs crate:foo -/// [struct Foo](struct.Foo.html) -pub struct $0Foo; -"#, - expect![[r#"[struct Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]], - ); - check_rewrite( - r#" -//- /main.rs crate:foo -/// [my Foo][foo] -/// -/// [foo]: Foo -pub struct $0Foo; -"#, - expect![[r#"[my Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]], - ); - } - - fn check_external_docs(ra_fixture: &str, expect: Expect) { - let (analysis, position) = fixture::position(ra_fixture); - let url = analysis.external_docs(position).unwrap().expect("could not find url for symbol"); - - expect.assert_eq(&url) - } - - fn check_rewrite(ra_fixture: &str, expect: Expect) { - let (analysis, position) = fixture::position(ra_fixture); - let sema = &Semantics::new(&*analysis.db); - let (cursor_def, docs) = def_under_cursor(sema, &position); - let res = rewrite_links(sema.db, docs.as_str(), cursor_def); - expect.assert_eq(&res) - } - - fn check_doc_links(ra_fixture: &str) { - let key_fn = |&(FileRange { file_id, range }, _): &_| (file_id, range.start()); - - let (analysis, position, mut expected) = fixture::annotations(ra_fixture); - expected.sort_by_key(key_fn); - let sema = &Semantics::new(&*analysis.db); - let (cursor_def, docs) = def_under_cursor(sema, &position); - let defs = extract_definitions_from_docs(&docs); - let actual: Vec<_> = defs - .into_iter() - .map(|(_, link, ns)| { - let def = resolve_doc_path_for_def(sema.db, cursor_def, &link, ns) - .unwrap_or_else(|| panic!("Failed to resolve {}", link)); - let nav_target = def.try_to_nav(sema.db).unwrap(); - let range = FileRange { - file_id: nav_target.file_id, - range: nav_target.focus_or_full_range(), - }; - (range, link) - }) - .sorted_by_key(key_fn) - .collect(); - assert_eq!(expected, actual); - } - - fn def_under_cursor( - sema: &Semantics, - position: &FilePosition, - ) -> (Definition, hir::Documentation) { - let (docs, def) = sema - .parse(position.file_id) - .syntax() - .token_at_offset(position.offset) - .left_biased() - .unwrap() - .ancestors() - .find_map(|it| node_to_def(sema, &it)) - .expect("no def found") - .unwrap(); - let docs = docs.expect("no docs found for cursor def"); - (def, docs) - } - - fn node_to_def( - sema: &Semantics, - node: &SyntaxNode, - ) -> Option, Definition)>> { - Some(match_ast! { - match node { - ast::SourceFile(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Module(def))), - ast::Module(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Module(def))), - ast::Fn(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Function(def))), - ast::Struct(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Adt(hir::Adt::Struct(def)))), - ast::Union(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Adt(hir::Adt::Union(def)))), - ast::Enum(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Adt(hir::Adt::Enum(def)))), - ast::Variant(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Variant(def))), - ast::Trait(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Trait(def))), - ast::Static(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Static(def))), - ast::Const(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Const(def))), - ast::TypeAlias(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::TypeAlias(def))), - ast::Impl(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::SelfType(def))), - ast::RecordField(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Field(def))), - ast::TupleField(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Field(def))), - ast::Macro(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::Macro(def))), - // ast::Use(it) => sema.to_def(&it).map(|def| (Box::new(it) as _, def.attrs(sema.db))), - _ => return None, - } - }) - } -}