//! 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,
// 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
});
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
link: &str,
ns: Option<hir::Namespace>,
) -> Option<Definition> {
- 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),
| 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(
(match_ast! {
match doc_token {
ast::Comment(comment) => 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,
}
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,
}
};
}
}
-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:
fn get_doc_link(db: &RootDatabase, def: Definition) -> Option<String> {
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()?;
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) {
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) {
url.join(target).ok().map(Into::into)
}
-fn crate_of_def(db: &RootDatabase, def: Definition) -> Option<Crate> {
- 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<String> {
def.canonical_module_path(db).map(|it| {
let mut path = String::new();
/// Rewrites a markdown document, applying 'callback' to each link.
fn map_links<'e>(
events: impl Iterator<Item = Event<'e>>,
- callback: impl Fn(&str, &str) -> (String, String),
+ callback: impl Fn(&str, &str) -> (Option<LinkType>, String, String),
) -> impl Iterator<Item = Event<'e>> {
let mut in_link = false;
- let mut link_target: Option<CowStr> = None;
+ // holds the origin link target on start event and the rewritten one on end event
+ let mut end_link_target: Option<CowStr> = 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<LinkType> = 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<Url> {
+fn get_doc_base_url(db: &RootDatabase, def: Definition) -> Option<Url> {
+ // 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(|| {
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)),
}
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()),
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"#]],
- );
- }
-
- #[test]
- fn rewrite_on_field() {
- check_rewrite(
- r#"
-//- /main.rs crate:foo
-pub struct Foo {
- /// [Foo](struct.Foo.html)
- fie$0ld: ()
-}
-"#,
- expect"#]],
- );
- }
-
- #[test]
- fn rewrite_struct() {
- check_rewrite(
- r#"
-//- /main.rs crate:foo
-/// [Foo]
-pub struct $0Foo;
-"#,
- expect"#]],
- );
- check_rewrite(
- r#"
-//- /main.rs crate:foo
-/// [`Foo`]
-pub struct $0Foo;
-"#,
- expect"#]],
- );
- check_rewrite(
- r#"
-//- /main.rs crate:foo
-/// [Foo](struct.Foo.html)
-pub struct $0Foo;
-"#,
- expect"#]],
- );
- check_rewrite(
- r#"
-//- /main.rs crate:foo
-/// [struct Foo](struct.Foo.html)
-pub struct $0Foo;
-"#,
- expect"#]],
- );
- check_rewrite(
- r#"
-//- /main.rs crate:foo
-/// [my Foo][foo]
-///
-/// [foo]: Foo
-pub struct $0Foo;
-"#,
- expect"#]],
- );
- }
-
- 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<RootDatabase>,
- 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<RootDatabase>,
- node: &SyntaxNode,
- ) -> Option<Option<(Option<hir::Documentation>, 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,
- }
- })
- }
-}
projects / rust.git / blobdiff