//! 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, MacroDef,
- ModuleDef,
-};
+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 Definition::ModuleDef(def) = definition {
- if let Some(target) = rewrite_url_link(db, Either::Left(def), target) {
- return (target, title.to_string());
- }
+ if let Some(target) = rewrite_url_link(db, definition, target) {
+ 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
def: Definition,
link: &str,
ns: Option<hir::Namespace>,
-) -> Option<Either<ModuleDef, MacroDef>> {
+) -> Option<Definition> {
match def {
- Definition::ModuleDef(def) => match def {
- hir::ModuleDef::Module(it) => it.resolve_doc_path(db, link, ns),
- hir::ModuleDef::Function(it) => it.resolve_doc_path(db, link, ns),
- hir::ModuleDef::Adt(it) => it.resolve_doc_path(db, link, ns),
- hir::ModuleDef::Variant(it) => it.resolve_doc_path(db, link, ns),
- hir::ModuleDef::Const(it) => it.resolve_doc_path(db, link, ns),
- hir::ModuleDef::Static(it) => it.resolve_doc_path(db, link, ns),
- hir::ModuleDef::Trait(it) => it.resolve_doc_path(db, link, ns),
- hir::ModuleDef::TypeAlias(it) => it.resolve_doc_path(db, link, ns),
- hir::ModuleDef::BuiltinType(_) => None,
- },
+ 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::Variant(it) => it.resolve_doc_path(db, link, ns),
+ Definition::Const(it) => it.resolve_doc_path(db, link, ns),
+ Definition::Static(it) => it.resolve_doc_path(db, link, ns),
+ Definition::Trait(it) => it.resolve_doc_path(db, link, ns),
+ Definition::TypeAlias(it) => it.resolve_doc_path(db, link, ns),
Definition::Macro(it) => it.resolve_doc_path(db, link, ns),
Definition::Field(it) => it.resolve_doc_path(db, link, ns),
- Definition::SelfType(_)
+ Definition::BuiltinAttr(_)
+ | Definition::ToolModule(_)
+ | Definition::BuiltinType(_)
+ | Definition::SelfType(_)
| Definition::Local(_)
| Definition::GenericParam(_)
| Definition::Label(_) => None,
}
+ .map(Definition::from)
}
pub(crate) fn doc_attributes(
) -> Option<(hir::AttrsWithOwner, Definition)> {
match_ast! {
match node {
- ast::SourceFile(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Module(def)))),
- ast::Module(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Module(def)))),
- ast::Fn(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Function(def)))),
- ast::Struct(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Adt(hir::Adt::Struct(def))))),
- ast::Union(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Adt(hir::Adt::Union(def))))),
- ast::Enum(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Adt(hir::Adt::Enum(def))))),
- ast::Variant(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Variant(def)))),
- ast::Trait(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Trait(def)))),
- ast::Static(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Static(def)))),
- ast::Const(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::Const(def)))),
- ast::TypeAlias(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::ModuleDef(hir::ModuleDef::TypeAlias(def)))),
+ ast::SourceFile(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Module(def))),
+ ast::Module(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Module(def))),
+ ast::Fn(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Function(def))),
+ ast::Struct(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Adt(hir::Adt::Struct(def)))),
+ ast::Union(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Adt(hir::Adt::Union(def)))),
+ ast::Enum(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Adt(hir::Adt::Enum(def)))),
+ ast::Variant(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Variant(def))),
+ ast::Trait(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Trait(def))),
+ ast::Static(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Static(def))),
+ ast::Const(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Const(def))),
+ ast::TypeAlias(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::TypeAlias(def))),
ast::Impl(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::SelfType(def))),
ast::RecordField(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Field(def))),
ast::TupleField(it) => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Field(def))),
(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,
}
};
let in_expansion_relative_range = in_expansion_range - descended_prefix_len - token_start;
// Apply relative range to the original input comment
let absolute_range = in_expansion_relative_range + original_start + prefix_len;
- let def = match resolve_doc_path_for_def(sema.db, def, &link, ns)? {
- Either::Left(it) => Definition::ModuleDef(it),
- Either::Right(it) => Definition::Macro(it),
- };
+ let def = resolve_doc_path_for_def(sema.db, def, &link, ns)?;
cb(def, node, absolute_range)
})
}
}
-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:
//
// This should cease to be a problem if RFC2988 (Stable Rustdoc URLs) is implemented
// https://github.com/rust-lang/rfcs/pull/2988
-fn get_doc_link(db: &RootDatabase, definition: Definition) -> Option<String> {
- let (target, frag) = match definition {
- Definition::ModuleDef(def) => {
- if let Some(assoc_item) = def.as_assoc_item(db) {
- let def = match assoc_item.container(db) {
- AssocItemContainer::Trait(t) => t.into(),
- AssocItemContainer::Impl(i) => i.self_ty(db).as_adt()?.into(),
- };
- let frag = get_assoc_item_fragment(db, assoc_item)?;
- (Either::Left(def), Some(frag))
- } else {
- (Either::Left(def), None)
- }
- }
- Definition::Field(field) => {
- let def = match field.parent_def(db) {
- hir::VariantDef::Struct(it) => it.into(),
- hir::VariantDef::Union(it) => it.into(),
- hir::VariantDef::Variant(it) => it.into(),
- };
- (Either::Left(def), Some(format!("structfield.{}", field.name(db))))
- }
- Definition::Macro(makro) => (Either::Right(makro), None),
- // FIXME impls
- Definition::SelfType(_) => return None,
- Definition::Local(_) | Definition::GenericParam(_) | Definition::Label(_) => return None,
- };
+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()?;
}
- url = url.join(&get_symbol_filename(db, target)?).ok()?;
+ url = url.join(&file).ok()?;
url.set_fragment(frag.as_deref());
Some(url.into())
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) {
url = url.join(&path).ok()?;
}
- let (resolved, frag) =
- if let Some(assoc_item) = resolved.left().and_then(|it| it.as_assoc_item(db)) {
- let resolved = match assoc_item.container(db) {
- AssocItemContainer::Trait(t) => t.into(),
- AssocItemContainer::Impl(i) => i.self_ty(db).as_adt()?.into(),
- };
- let frag = get_assoc_item_fragment(db, assoc_item)?;
- (Either::Left(resolved), Some(frag))
- } else {
- (resolved, None)
- };
- url = url.join(&get_symbol_filename(db, resolved)?).ok()?;
+ url = url.join(&file).ok()?;
url.set_fragment(frag.as_deref());
Some((url.into(), strip_prefixes_suffixes(title).to_string()))
}
/// Try to resolve path to local documentation via path-based links (i.e. `../gateway/struct.Shard.html`).
-fn rewrite_url_link(
- db: &RootDatabase,
- def: Either<ModuleDef, MacroDef>,
- target: &str,
-) -> Option<String> {
+fn rewrite_url_link(db: &RootDatabase, def: Definition, target: &str) -> Option<String> {
if !(target.contains('#') || target.contains(".html")) {
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 = url.join(&path).ok()?;
}
- url = url.join(&get_symbol_filename(db, def)?).ok()?;
+ url = url.join(&file).ok()?;
+ url.set_fragment(frag.as_deref());
url.join(target).ok().map(Into::into)
}
-fn crate_of_def(db: &RootDatabase, def: Either<ModuleDef, MacroDef>) -> Option<Crate> {
- let krate = match def {
- // Definition::module gives back the parent module, we don't want that as it fails for root modules
- Either::Left(ModuleDef::Module(module)) => module.krate(),
- Either::Left(def) => def.module(db)?.krate(),
- Either::Right(def) => def.module(db)?.krate(),
- };
- Some(krate)
-}
-
-fn mod_path_of_def(db: &RootDatabase, def: Either<ModuleDef, MacroDef>) -> Option<String> {
- match def {
- Either::Left(def) => def.canonical_module_path(db).map(|it| {
- let mut path = String::new();
- it.flat_map(|it| it.name(db)).for_each(|name| format_to!(path, "{}/", name));
- path
- }),
- Either::Right(def) => {
- def.module(db).map(|it| it.path_to_root(db).into_iter().rev()).map(|it| {
- let mut path = String::new();
- it.flat_map(|it| it.name(db)).for_each(|name| format_to!(path, "{}/", name));
- path
- })
- }
- }
+fn mod_path_of_def(db: &RootDatabase, def: Definition) -> Option<String> {
+ def.canonical_module_path(db).map(|it| {
+ let mut path = String::new();
+ it.flat_map(|it| it.name(db)).for_each(|name| format_to!(path, "{}/", name));
+ path
+ })
}
/// 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(|| {
/// https://doc.rust-lang.org/std/iter/trait.Iterator.html#tymethod.next
/// ^^^^^^^^^^^^^^^^^^^
/// ```
-fn get_symbol_filename(
+fn filename_and_frag_for_def(
db: &dyn HirDatabase,
- definition: Either<ModuleDef, MacroDef>,
-) -> Option<String> {
- let res = match definition {
- Either::Left(definition) => match definition {
- ModuleDef::Adt(adt) => match adt {
- Adt::Struct(s) => format!("struct.{}.html", s.name(db)),
- Adt::Enum(e) => format!("enum.{}.html", e.name(db)),
- Adt::Union(u) => format!("union.{}.html", u.name(db)),
- },
- ModuleDef::Module(m) => match m.name(db) {
- Some(name) => format!("{}/index.html", name),
- None => String::from("index.html"),
+ def: Definition,
+) -> Option<(Definition, String, Option<String>)> {
+ if let Some(assoc_item) = def.as_assoc_item(db) {
+ let def = match assoc_item.container(db) {
+ AssocItemContainer::Trait(t) => t.into(),
+ AssocItemContainer::Impl(i) => i.self_ty(db).as_adt()?.into(),
+ };
+ let (_, file, _) = filename_and_frag_for_def(db, def)?;
+ let frag = get_assoc_item_fragment(db, assoc_item)?;
+ return Some((def, file, Some(frag)));
+ }
+
+ let res = match def {
+ Definition::Adt(adt) => match adt {
+ Adt::Struct(s) => format!("struct.{}.html", s.name(db)),
+ Adt::Enum(e) => format!("enum.{}.html", e.name(db)),
+ Adt::Union(u) => format!("union.{}.html", u.name(db)),
+ },
+ Definition::Module(m) => match m.name(db) {
+ // `#[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),
},
- ModuleDef::Trait(t) => format!("trait.{}.html", t.name(db)),
- ModuleDef::TypeAlias(t) => format!("type.{}.html", t.name(db)),
- ModuleDef::BuiltinType(t) => format!("primitive.{}.html", t.name()),
- ModuleDef::Function(f) => format!("fn.{}.html", f.name(db)),
- ModuleDef::Variant(ev) => {
- format!("enum.{}.html#variant.{}", ev.parent_enum(db).name(db), ev.name(db))
- }
- ModuleDef::Const(c) => format!("const.{}.html", c.name(db)?),
- ModuleDef::Static(s) => format!("static.{}.html", s.name(db)?),
+ None => String::from("index.html"),
},
- Either::Right(mac) => format!("macro.{}.html", mac.name(db)?),
+ Definition::Trait(t) => format!("trait.{}.html", t.name(db)),
+ Definition::TypeAlias(t) => format!("type.{}.html", t.name(db)),
+ Definition::BuiltinType(t) => format!("primitive.{}.html", t.name()),
+ Definition::Function(f) => format!("fn.{}.html", f.name(db)),
+ Definition::Variant(ev) => {
+ format!("enum.{}.html#variant.{}", ev.parent_enum(db).name(db), ev.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::Field(field) => {
+ let def = match field.parent_def(db) {
+ hir::VariantDef::Struct(it) => Definition::Adt(it.into()),
+ hir::VariantDef::Union(it) => Definition::Adt(it.into()),
+ hir::VariantDef::Variant(it) => Definition::Variant(it),
+ };
+ let (_, file, _) = filename_and_frag_for_def(db, def)?;
+ return Some((def, file, Some(format!("structfield.{}", field.name(db)))));
+ }
+ Definition::SelfType(impl_) => {
+ let adt = impl_.self_ty(db).as_adt()?.into();
+ let (_, file, _) = filename_and_frag_for_def(db, adt)?;
+ // FIXME fragment numbering
+ return Some((adt, file, Some(String::from("impl"))));
+ }
+ Definition::Local(_)
+ | Definition::GenericParam(_)
+ | Definition::Label(_)
+ | Definition::BuiltinAttr(_)
+ | Definition::ToolModule(_) => return None,
};
- Some(res)
+
+ Some((def, res, None))
}
/// Get the fragment required to link to a specific field, method, associated type, or associated constant.
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::{display::TryToNav, fixture};
-
- 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() {
- // FIXME: Should be
- // [Foo](https://docs.rs/test/*/test/struct.Foo.html)
- 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::ModuleDef(hir::ModuleDef::Module(def)))),
- ast::Module(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Module(def)))),
- ast::Fn(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Function(def)))),
- ast::Struct(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Adt(hir::Adt::Struct(def))))),
- ast::Union(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Adt(hir::Adt::Union(def))))),
- ast::Enum(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Adt(hir::Adt::Enum(def))))),
- ast::Variant(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Variant(def)))),
- ast::Trait(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Trait(def)))),
- ast::Static(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Static(def)))),
- ast::Const(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::Const(def)))),
- ast::TypeAlias(it) => sema.to_def(&it).map(|def| (def.docs(sema.db), Definition::ModuleDef(hir::ModuleDef::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