Merge #8245

8245: Properly resolve intra doc links in hover and goto_definition r=matklad a=Veykril

Unfortunately involves a bit of weird workarounds due to pulldown_cmark's incorrect lifetimes on `BrokenLinkCallback`... I should probably open an issue there asking for the fixes to be pushed to a release since they already exist in the repo for quite some time it seems.

Fixes #8258, Fixes #8238

Co-authored-by: Lukas Wirth <lukastw97@gmail.com>

Author: bors[bot]

crates/hir_def/src/attr.rs

@@ -1,6 +1,10 @@
 //! A higher level attributes based on TokenTree, with also some shortcuts.
 
-use std::{ops, sync::Arc};
+use std::{
+    convert::{TryFrom, TryInto},
+    ops,
+    sync::Arc,
+};
 
 use base_db::CrateId;
 use cfg::{CfgExpr, CfgOptions};
@@ -12,7 +16,7 @@ use mbe::ast_to_token_tree;
 use smallvec::{smallvec, SmallVec};
 use syntax::{
     ast::{self, AstNode, AttrsOwner},
-    match_ast, AstToken, SmolStr, SyntaxNode,
+    match_ast, AstToken, SmolStr, SyntaxNode, TextRange, TextSize,
 };
 use tt::Subtree;
 
@@ -452,6 +456,55 @@ impl AttrsWithOwner {
                 .collect(),
         }
     }
+
+    pub fn docs_with_rangemap(
+        &self,
+        db: &dyn DefDatabase,
+    ) -> Option<(Documentation, DocsRangeMap)> {
+        // FIXME: code duplication in `docs` above
+        let docs = self.by_key("doc").attrs().flat_map(|attr| match attr.input.as_ref()? {
+            AttrInput::Literal(s) => Some((s, attr.index)),
+            AttrInput::TokenTree(_) => None,
+        });
+        let indent = docs
+            .clone()
+            .flat_map(|(s, _)| s.lines())
+            .filter(|line| !line.chars().all(|c| c.is_whitespace()))
+            .map(|line| line.chars().take_while(|c| c.is_whitespace()).count())
+            .min()
+            .unwrap_or(0);
+        let mut buf = String::new();
+        let mut mapping = Vec::new();
+        for (doc, idx) in docs {
+            // str::lines doesn't yield anything for the empty string
+            if !doc.is_empty() {
+                for line in doc.split('\n') {
+                    let line = line.trim_end();
+                    let line_len = line.len();
+                    let (offset, line) = match line.char_indices().nth(indent) {
+                        Some((offset, _)) => (offset, &line[offset..]),
+                        None => (0, line),
+                    };
+                    let buf_offset = buf.len();
+                    buf.push_str(line);
+                    mapping.push((
+                        TextRange::new(buf_offset.try_into().ok()?, buf.len().try_into().ok()?),
+                        idx,
+                        TextRange::new(offset.try_into().ok()?, line_len.try_into().ok()?),
+                    ));
+                    buf.push('\n');
+                }
+            } else {
+                buf.push('\n');
+            }
+        }
+        buf.pop();
+        if buf.is_empty() {
+            None
+        } else {
+            Some((Documentation(buf), DocsRangeMap { mapping, source: self.source_map(db).attrs }))
+        }
+    }
 }
 
 fn inner_attributes(
@@ -508,6 +561,44 @@ impl AttrSourceMap {
     }
 }
 
+/// A struct to map text ranges from [`Documentation`] back to TextRanges in the syntax tree.
+pub struct DocsRangeMap {
+    source: Vec<InFile<Either<ast::Attr, ast::Comment>>>,
+    // (docstring-line-range, attr_index, attr-string-range)
+    // a mapping from the text range of a line of the [`Documentation`] to the attribute index and
+    // the original (untrimmed) syntax doc line
+    mapping: Vec<(TextRange, u32, TextRange)>,
+}
+
+impl DocsRangeMap {
+    pub fn map(&self, range: TextRange) -> Option<InFile<TextRange>> {
+        let found = self.mapping.binary_search_by(|(probe, ..)| probe.ordering(range)).ok()?;
+        let (line_docs_range, idx, original_line_src_range) = self.mapping[found].clone();
+        if !line_docs_range.contains_range(range) {
+            return None;
+        }
+
+        let relative_range = range - line_docs_range.start();
+
+        let &InFile { file_id, value: ref source } = &self.source[idx as usize];
+        match source {
+            Either::Left(_) => None, // FIXME, figure out a nice way to handle doc attributes here
+            // as well as for whats done in syntax highlight doc injection
+            Either::Right(comment) => {
+                let text_range = comment.syntax().text_range();
+                let range = TextRange::at(
+                    text_range.start()
+                        + TextSize::try_from(comment.prefix().len()).ok()?
+                        + original_line_src_range.start()
+                        + relative_range.start(),
+                    text_range.len().min(range.len()),
+                );
+                Some(InFile { file_id, value: range })
+            }
+        }
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Attr {
     index: u32,

crates/ide/src/doc_links.rs

@@ -1,6 +1,9 @@
 //! Extracts, resolves and rewrites links and intra-doc links in markdown documentation.
 
-use std::{convert::TryFrom, iter::once, ops::Range};
+use std::{
+    convert::{TryFrom, TryInto},
+    iter::once,
+};
 
 use itertools::Itertools;
 use pulldown_cmark::{BrokenLink, CowStr, Event, InlineStr, LinkType, Options, Parser, Tag};
@@ -16,8 +19,7 @@ use ide_db::{
     RootDatabase,
 };
 use syntax::{
-    ast, match_ast, AstNode, AstToken, SyntaxKind::*, SyntaxNode, SyntaxToken, TextRange, TextSize,
-    TokenAtOffset, T,
+    ast, match_ast, AstNode, SyntaxKind::*, SyntaxNode, SyntaxToken, TextRange, TokenAtOffset, T,
 };
 
 use crate::{FilePosition, Semantics};
@@ -26,12 +28,7 @@ pub(crate) type DocumentationLink = String;
 
 /// Rewrite documentation links in markdown to point to an online host (e.g. docs.rs)
 pub(crate) fn rewrite_links(db: &RootDatabase, markdown: &str, definition: &Definition) -> String {
-    let mut cb = |link: BrokenLink| {
-        Some((
-            /*url*/ link.reference.to_owned().into(),
-            /*title*/ link.reference.to_owned().into(),
-        ))
-    };
+    let mut cb = broken_link_clone_cb;
     let doc = Parser::new_with_broken_link_callback(markdown, Options::empty(), Some(&mut cb));
 
     let doc = map_links(doc, |target, title: &str| {
@@ -123,74 +120,27 @@ pub(crate) fn external_docs(
 /// Extracts all links from a given markdown text.
 pub(crate) fn extract_definitions_from_markdown(
     markdown: &str,
-) -> Vec<(Range<usize>, String, Option<hir::Namespace>)> {
-    let mut res = vec![];
-    let mut cb = |link: BrokenLink| {
-        // 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(),
-        ))
-    };
-    let doc = Parser::new_with_broken_link_callback(markdown, Options::empty(), Some(&mut cb));
-    for (event, range) in doc.into_offset_iter() {
+) -> Vec<(TextRange, String, Option<hir::Namespace>)> {
+    Parser::new_with_broken_link_callback(
+        markdown,
+        Options::empty(),
+        Some(&mut broken_link_clone_cb),
+    )
+    .into_offset_iter()
+    .filter_map(|(event, range)| {
         if let Event::Start(Tag::Link(_, target, title)) = event {
             let link = if target.is_empty() { title } else { target };
             let (link, ns) = parse_intra_doc_link(&link);
-            res.push((range, link.to_string(), ns));
-        }
-    }
-    res
-}
-
-/// Extracts a link from a comment at the given position returning the spanning range, link and
-/// optionally it's namespace.
-pub(crate) fn extract_positioned_link_from_comment(
-    position: TextSize,
-    comment: &ast::Comment,
-) -> Option<(TextRange, String, Option<hir::Namespace>)> {
-    let doc_comment = comment.doc_comment()?;
-    let comment_start =
-        comment.syntax().text_range().start() + TextSize::from(comment.prefix().len() as u32);
-    let def_links = extract_definitions_from_markdown(doc_comment);
-    let (range, def_link, ns) =
-        def_links.into_iter().find_map(|(Range { start, end }, def_link, ns)| {
-            let range = TextRange::at(
-                comment_start + TextSize::from(start as u32),
-                TextSize::from((end - start) as u32),
-            );
-            range.contains(position).then(|| (range, def_link, ns))
-        })?;
-    Some((range, def_link, ns))
-}
-
-/// Turns a syntax node into it's [`Definition`] if it can hold docs.
-pub(crate) fn doc_owner_to_def(
-    sema: &Semantics<RootDatabase>,
-    item: &SyntaxNode,
-) -> Option<Definition> {
-    let res: hir::ModuleDef = match_ast! {
-        match item {
-            ast::SourceFile(_it) => sema.scope(item).module()?.into(),
-            ast::Fn(it) => sema.to_def(&it)?.into(),
-            ast::Struct(it) => sema.to_def(&it)?.into(),
-            ast::Enum(it) => sema.to_def(&it)?.into(),
-            ast::Union(it) => sema.to_def(&it)?.into(),
-            ast::Trait(it) => sema.to_def(&it)?.into(),
-            ast::Const(it) => sema.to_def(&it)?.into(),
-            ast::Static(it) => sema.to_def(&it)?.into(),
-            ast::TypeAlias(it) => sema.to_def(&it)?.into(),
-            ast::Variant(it) => sema.to_def(&it)?.into(),
-            ast::Trait(it) => sema.to_def(&it)?.into(),
-            ast::Impl(it) => return sema.to_def(&it).map(Definition::SelfType),
-            ast::Macro(it) => return sema.to_def(&it).map(Definition::Macro),
-            ast::TupleField(it) => return sema.to_def(&it).map(Definition::Field),
-            ast::RecordField(it) => return sema.to_def(&it).map(Definition::Field),
-            _ => return None,
+            Some((
+                TextRange::new(range.start.try_into().ok()?, range.end.try_into().ok()?),
+                link.to_string(),
+                ns,
+            ))
+        } else {
+            None
         }
-    };
-    Some(Definition::ModuleDef(res))
+    })
+    .collect()
 }
 
 pub(crate) fn resolve_doc_path_for_def(
@@ -220,6 +170,42 @@ pub(crate) fn resolve_doc_path_for_def(
     }
 }
 
+pub(crate) fn doc_attributes(
+    sema: &Semantics<RootDatabase>,
+    node: &SyntaxNode,
+) -> 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::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))),
+            ast::Macro(it)       => sema.to_def(&it).map(|def| (def.attrs(sema.db), Definition::Macro(def))),
+            // ast::Use(it) => sema.to_def(&it).map(|def| (Box::new(it) as _, def.attrs(sema.db))),
+            _ => 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(),
+    ))
+}
+
 // FIXME:
 // BUG: For Option::Some
 // Returns https://doc.rust-lang.org/nightly/core/prelude/v1/enum.Option.html#variant.Some

crates/ide/src/goto_definition.rs

@@ -1,5 +1,5 @@
 use either::Either;
-use hir::Semantics;
+use hir::{InFile, Semantics};
 use ide_db::{
     defs::{NameClass, NameRefClass},
     RootDatabase,
@@ -8,7 +8,7 @@ use syntax::{ast, match_ast, AstNode, AstToken, SyntaxKind::*, SyntaxToken, Toke
 
 use crate::{
     display::TryToNav,
-    doc_links::{doc_owner_to_def, extract_positioned_link_from_comment, resolve_doc_path_for_def},
+    doc_links::{doc_attributes, extract_definitions_from_markdown, resolve_doc_path_for_def},
     FilePosition, NavigationTarget, RangeInfo,
 };
 
@@ -32,9 +32,16 @@ pub(crate) fn goto_definition(
     let original_token = pick_best(file.token_at_offset(position.offset))?;
     let token = sema.descend_into_macros(original_token.clone());
     let parent = token.parent()?;
-    if let Some(comment) = ast::Comment::cast(token) {
-        let (_, link, ns) = extract_positioned_link_from_comment(position.offset, &comment)?;
-        let def = doc_owner_to_def(&sema, &parent)?;
+    if let Some(_) = ast::Comment::cast(token) {
+        let (attributes, def) = doc_attributes(&sema, &parent)?;
+
+        let (docs, doc_mapping) = attributes.docs_with_rangemap(db)?;
+        let (_, link, ns) =
+            extract_definitions_from_markdown(docs.as_str()).into_iter().find(|(range, ..)| {
+                doc_mapping.map(range.clone()).map_or(false, |InFile { file_id, value: range }| {
+                    file_id == position.file_id.into() && range.contains(position.offset)
+                })
+            })?;
         let nav = resolve_doc_path_for_def(db, def, &link, ns)?.try_to_nav(db)?;
         return Some(RangeInfo::new(original_token.text_range(), vec![nav]));
     }
@@ -1160,4 +1167,25 @@ fn fn_macro() {}
             "#,
         )
     }
+
+    #[test]
+    fn goto_intra_doc_links() {
+        check(
+            r#"
+
+pub mod theitem {
+    /// This is the item. Cool!
+    pub struct TheItem;
+             //^^^^^^^
+}
+
+/// Gives you a [`TheItem$0`].
+///
+/// [`TheItem`]: theitem::TheItem
+pub fn gimme() -> theitem::TheItem {
+    theitem::TheItem
+}
+"#,
+        );
+    }
 }