diff options
author | bors[bot] <26634292+bors[bot]@users.noreply.github.com> | 2020-10-12 08:38:24 +0100 |
---|---|---|
committer | GitHub <[email protected]> | 2020-10-12 08:38:24 +0100 |
commit | 518f6d772482c7c58e59081f340947087a9b4800 (patch) | |
tree | d904f1b98cad63944b4c405238d8b3938a9debb9 /crates/ide | |
parent | d5fcedb38eec33e2eb12ed550a9b90f6950855fe (diff) | |
parent | 3bd4fe96dce17eb2bff380389b24ea325bf54803 (diff) |
Merge #5917
5917: Add a command to open docs for the symbol under the cursor r=matklad a=zacps
#### Todo
- [ ] Decide if there should be a default keybind or context menu entry
- [x] Figure out how to get the documentation path for methods and other non-top-level defs
- [x] Design the protocol extension. In future we'll probably want parameters for local/remote documentation URLs, so that should maybe be done in this PR?
- [x] Code organisation
- [x] Tests
Co-authored-by: Zac Pullar-Strecker <[email protected]>
Diffstat (limited to 'crates/ide')
-rw-r--r-- | crates/ide/src/doc_links.rs (renamed from crates/ide/src/link_rewrite.rs) | 285 | ||||
-rw-r--r-- | crates/ide/src/hover.rs | 2 | ||||
-rw-r--r-- | crates/ide/src/lib.rs | 10 |
3 files changed, 287 insertions, 10 deletions
diff --git a/crates/ide/src/link_rewrite.rs b/crates/ide/src/doc_links.rs index c317a2379..06af36b73 100644 --- a/crates/ide/src/link_rewrite.rs +++ b/crates/ide/src/doc_links.rs | |||
@@ -1,13 +1,27 @@ | |||
1 | //! Resolves and rewrites links in markdown documentation. | 1 | //! Resolves and rewrites links in markdown documentation. |
2 | //! | ||
3 | //! Most of the implementation can be found in [`hir::doc_links`]. | ||
4 | 2 | ||
5 | use hir::{Adt, Crate, HasAttrs, ModuleDef}; | 3 | use std::iter::once; |
6 | use ide_db::{defs::Definition, RootDatabase}; | 4 | |
5 | use itertools::Itertools; | ||
7 | use pulldown_cmark::{CowStr, Event, LinkType, Options, Parser, Tag}; | 6 | use pulldown_cmark::{CowStr, Event, LinkType, Options, Parser, Tag}; |
8 | use pulldown_cmark_to_cmark::{cmark_with_options, Options as CmarkOptions}; | 7 | use pulldown_cmark_to_cmark::{cmark_with_options, Options as CmarkOptions}; |
9 | use url::Url; | 8 | use url::Url; |
10 | 9 | ||
10 | use hir::{ | ||
11 | db::{DefDatabase, HirDatabase}, | ||
12 | Adt, AsAssocItem, AsName, AssocItem, AssocItemContainer, Crate, Field, HasAttrs, ItemInNs, | ||
13 | ModuleDef, | ||
14 | }; | ||
15 | use ide_db::{ | ||
16 | defs::{classify_name, classify_name_ref, Definition}, | ||
17 | RootDatabase, | ||
18 | }; | ||
19 | use syntax::{ast, match_ast, AstNode, SyntaxKind::*, SyntaxToken, TokenAtOffset, T}; | ||
20 | |||
21 | use crate::{FilePosition, Semantics}; | ||
22 | |||
23 | pub type DocumentationLink = String; | ||
24 | |||
11 | /// Rewrite documentation links in markdown to point to an online host (e.g. docs.rs) | 25 | /// Rewrite documentation links in markdown to point to an online host (e.g. docs.rs) |
12 | pub fn rewrite_links(db: &RootDatabase, markdown: &str, definition: &Definition) -> String { | 26 | pub fn rewrite_links(db: &RootDatabase, markdown: &str, definition: &Definition) -> String { |
13 | let doc = Parser::new_with_broken_link_callback( | 27 | let doc = Parser::new_with_broken_link_callback( |
@@ -80,6 +94,70 @@ pub fn remove_links(markdown: &str) -> String { | |||
80 | out | 94 | out |
81 | } | 95 | } |
82 | 96 | ||
97 | // FIXME: | ||
98 | // BUG: For Option::Some | ||
99 | // Returns https://doc.rust-lang.org/nightly/core/prelude/v1/enum.Option.html#variant.Some | ||
100 | // Instead of https://doc.rust-lang.org/nightly/core/option/enum.Option.html | ||
101 | // | ||
102 | // This should cease to be a problem if RFC2988 (Stable Rustdoc URLs) is implemented | ||
103 | // https://github.com/rust-lang/rfcs/pull/2988 | ||
104 | fn get_doc_link(db: &RootDatabase, definition: Definition) -> Option<String> { | ||
105 | // Get the outermost definition for the moduledef. This is used to resolve the public path to the type, | ||
106 | // then we can join the method, field, etc onto it if required. | ||
107 | let target_def: ModuleDef = match definition { | ||
108 | Definition::ModuleDef(moddef) => match moddef { | ||
109 | ModuleDef::Function(f) => f | ||
110 | .as_assoc_item(db) | ||
111 | .and_then(|assoc| match assoc.container(db) { | ||
112 | AssocItemContainer::Trait(t) => Some(t.into()), | ||
113 | AssocItemContainer::ImplDef(impld) => { | ||
114 | impld.target_ty(db).as_adt().map(|adt| adt.into()) | ||
115 | } | ||
116 | }) | ||
117 | .unwrap_or_else(|| f.clone().into()), | ||
118 | moddef => moddef, | ||
119 | }, | ||
120 | Definition::Field(f) => f.parent_def(db).into(), | ||
121 | // FIXME: Handle macros | ||
122 | _ => return None, | ||
123 | }; | ||
124 | |||
125 | let ns = ItemInNs::from(target_def.clone()); | ||
126 | |||
127 | let module = definition.module(db)?; | ||
128 | let krate = module.krate(); | ||
129 | let import_map = db.import_map(krate.into()); | ||
130 | let base = once(krate.declaration_name(db)?.to_string()) | ||
131 | .chain(import_map.path_of(ns)?.segments.iter().map(|name| name.to_string())) | ||
132 | .join("/"); | ||
133 | |||
134 | let filename = get_symbol_filename(db, &target_def); | ||
135 | let fragment = match definition { | ||
136 | Definition::ModuleDef(moddef) => match moddef { | ||
137 | ModuleDef::Function(f) => { | ||
138 | get_symbol_fragment(db, &FieldOrAssocItem::AssocItem(AssocItem::Function(f))) | ||
139 | } | ||
140 | ModuleDef::Const(c) => { | ||
141 | get_symbol_fragment(db, &FieldOrAssocItem::AssocItem(AssocItem::Const(c))) | ||
142 | } | ||
143 | ModuleDef::TypeAlias(ty) => { | ||
144 | get_symbol_fragment(db, &FieldOrAssocItem::AssocItem(AssocItem::TypeAlias(ty))) | ||
145 | } | ||
146 | _ => None, | ||
147 | }, | ||
148 | Definition::Field(field) => get_symbol_fragment(db, &FieldOrAssocItem::Field(field)), | ||
149 | _ => None, | ||
150 | }; | ||
151 | |||
152 | get_doc_url(db, &krate) | ||
153 | .and_then(|url| url.join(&base).ok()) | ||
154 | .and_then(|url| filename.as_deref().and_then(|f| url.join(f).ok())) | ||
155 | .and_then( | ||
156 | |url| if let Some(fragment) = fragment { url.join(&fragment).ok() } else { Some(url) }, | ||
157 | ) | ||
158 | .map(|url| url.into_string()) | ||
159 | } | ||
160 | |||
83 | fn rewrite_intra_doc_link( | 161 | fn rewrite_intra_doc_link( |
84 | db: &RootDatabase, | 162 | db: &RootDatabase, |
85 | def: Definition, | 163 | def: Definition, |
@@ -138,7 +216,29 @@ fn rewrite_url_link(db: &RootDatabase, def: ModuleDef, target: &str) -> Option<S | |||
138 | .map(|url| url.into_string()) | 216 | .map(|url| url.into_string()) |
139 | } | 217 | } |
140 | 218 | ||
141 | // Rewrites a markdown document, resolving links using `callback` and additionally striping prefixes/suffixes on link titles. | 219 | /// Retrieve a link to documentation for the given symbol. |
220 | pub(crate) fn external_docs( | ||
221 | db: &RootDatabase, | ||
222 | position: &FilePosition, | ||
223 | ) -> Option<DocumentationLink> { | ||
224 | let sema = Semantics::new(db); | ||
225 | let file = sema.parse(position.file_id).syntax().clone(); | ||
226 | let token = pick_best(file.token_at_offset(position.offset))?; | ||
227 | let token = sema.descend_into_macros(token); | ||
228 | |||
229 | let node = token.parent(); | ||
230 | let definition = match_ast! { | ||
231 | match node { | ||
232 | ast::NameRef(name_ref) => classify_name_ref(&sema, &name_ref).map(|d| d.definition(sema.db)), | ||
233 | ast::Name(name) => classify_name(&sema, &name).map(|d| d.definition(sema.db)), | ||
234 | _ => None, | ||
235 | } | ||
236 | }; | ||
237 | |||
238 | get_doc_link(db, definition?) | ||
239 | } | ||
240 | |||
241 | /// Rewrites a markdown document, applying 'callback' to each link. | ||
142 | fn map_links<'e>( | 242 | fn map_links<'e>( |
143 | events: impl Iterator<Item = Event<'e>>, | 243 | events: impl Iterator<Item = Event<'e>>, |
144 | callback: impl Fn(&str, &str) -> (String, String), | 244 | callback: impl Fn(&str, &str) -> (String, String), |
@@ -239,6 +339,12 @@ fn ns_from_intra_spec(s: &str) -> Option<hir::Namespace> { | |||
239 | .next() | 339 | .next() |
240 | } | 340 | } |
241 | 341 | ||
342 | /// Get the root URL for the documentation of a crate. | ||
343 | /// | ||
344 | /// ``` | ||
345 | /// https://doc.rust-lang.org/std/iter/trait.Iterator.html#tymethod.next | ||
346 | /// ^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
347 | /// ``` | ||
242 | fn get_doc_url(db: &RootDatabase, krate: &Crate) -> Option<Url> { | 348 | fn get_doc_url(db: &RootDatabase, krate: &Crate) -> Option<Url> { |
243 | krate | 349 | krate |
244 | .get_html_root_url(db) | 350 | .get_html_root_url(db) |
@@ -255,8 +361,11 @@ fn get_doc_url(db: &RootDatabase, krate: &Crate) -> Option<Url> { | |||
255 | 361 | ||
256 | /// Get the filename and extension generated for a symbol by rustdoc. | 362 | /// Get the filename and extension generated for a symbol by rustdoc. |
257 | /// | 363 | /// |
258 | /// Example: `struct.Shard.html` | 364 | /// ``` |
259 | fn get_symbol_filename(db: &RootDatabase, definition: &ModuleDef) -> Option<String> { | 365 | /// https://doc.rust-lang.org/std/iter/trait.Iterator.html#tymethod.next |
366 | /// ^^^^^^^^^^^^^^^^^^^ | ||
367 | /// ``` | ||
368 | fn get_symbol_filename(db: &dyn HirDatabase, definition: &ModuleDef) -> Option<String> { | ||
260 | Some(match definition { | 369 | Some(match definition { |
261 | ModuleDef::Adt(adt) => match adt { | 370 | ModuleDef::Adt(adt) => match adt { |
262 | Adt::Struct(s) => format!("struct.{}.html", s.name(db)), | 371 | Adt::Struct(s) => format!("struct.{}.html", s.name(db)), |
@@ -266,7 +375,7 @@ fn get_symbol_filename(db: &RootDatabase, definition: &ModuleDef) -> Option<Stri | |||
266 | ModuleDef::Module(_) => "index.html".to_string(), | 375 | ModuleDef::Module(_) => "index.html".to_string(), |
267 | ModuleDef::Trait(t) => format!("trait.{}.html", t.name(db)), | 376 | ModuleDef::Trait(t) => format!("trait.{}.html", t.name(db)), |
268 | ModuleDef::TypeAlias(t) => format!("type.{}.html", t.name(db)), | 377 | ModuleDef::TypeAlias(t) => format!("type.{}.html", t.name(db)), |
269 | ModuleDef::BuiltinType(t) => format!("primitive.{}.html", t), | 378 | ModuleDef::BuiltinType(t) => format!("primitive.{}.html", t.as_name()), |
270 | ModuleDef::Function(f) => format!("fn.{}.html", f.name(db)), | 379 | ModuleDef::Function(f) => format!("fn.{}.html", f.name(db)), |
271 | ModuleDef::EnumVariant(ev) => { | 380 | ModuleDef::EnumVariant(ev) => { |
272 | format!("enum.{}.html#variant.{}", ev.parent_enum(db).name(db), ev.name(db)) | 381 | format!("enum.{}.html#variant.{}", ev.parent_enum(db).name(db), ev.name(db)) |
@@ -275,3 +384,163 @@ fn get_symbol_filename(db: &RootDatabase, definition: &ModuleDef) -> Option<Stri | |||
275 | ModuleDef::Static(s) => format!("static.{}.html", s.name(db)?), | 384 | ModuleDef::Static(s) => format!("static.{}.html", s.name(db)?), |
276 | }) | 385 | }) |
277 | } | 386 | } |
387 | |||
388 | enum FieldOrAssocItem { | ||
389 | Field(Field), | ||
390 | AssocItem(AssocItem), | ||
391 | } | ||
392 | |||
393 | /// Get the fragment required to link to a specific field, method, associated type, or associated constant. | ||
394 | /// | ||
395 | /// ``` | ||
396 | /// https://doc.rust-lang.org/std/iter/trait.Iterator.html#tymethod.next | ||
397 | /// ^^^^^^^^^^^^^^ | ||
398 | /// ``` | ||
399 | fn get_symbol_fragment(db: &dyn HirDatabase, field_or_assoc: &FieldOrAssocItem) -> Option<String> { | ||
400 | Some(match field_or_assoc { | ||
401 | FieldOrAssocItem::Field(field) => format!("#structfield.{}", field.name(db)), | ||
402 | FieldOrAssocItem::AssocItem(assoc) => match assoc { | ||
403 | AssocItem::Function(function) => { | ||
404 | let is_trait_method = matches!( | ||
405 | function.as_assoc_item(db).map(|assoc| assoc.container(db)), | ||
406 | Some(AssocItemContainer::Trait(..)) | ||
407 | ); | ||
408 | // This distinction may get more complicated when specialisation is available. | ||
409 | // Rustdoc makes this decision based on whether a method 'has defaultness'. | ||
410 | // Currently this is only the case for provided trait methods. | ||
411 | if is_trait_method && !function.has_body(db) { | ||
412 | format!("#tymethod.{}", function.name(db)) | ||
413 | } else { | ||
414 | format!("#method.{}", function.name(db)) | ||
415 | } | ||
416 | } | ||
417 | AssocItem::Const(constant) => format!("#associatedconstant.{}", constant.name(db)?), | ||
418 | AssocItem::TypeAlias(ty) => format!("#associatedtype.{}", ty.name(db)), | ||
419 | }, | ||
420 | }) | ||
421 | } | ||
422 | |||
423 | fn pick_best(tokens: TokenAtOffset<SyntaxToken>) -> Option<SyntaxToken> { | ||
424 | return tokens.max_by_key(priority); | ||
425 | fn priority(n: &SyntaxToken) -> usize { | ||
426 | match n.kind() { | ||
427 | IDENT | INT_NUMBER => 3, | ||
428 | T!['('] | T![')'] => 2, | ||
429 | kind if kind.is_trivia() => 0, | ||
430 | _ => 1, | ||
431 | } | ||
432 | } | ||
433 | } | ||
434 | |||
435 | #[cfg(test)] | ||
436 | mod tests { | ||
437 | use expect_test::{expect, Expect}; | ||
438 | |||
439 | use crate::fixture; | ||
440 | |||
441 | fn check(ra_fixture: &str, expect: Expect) { | ||
442 | let (analysis, position) = fixture::position(ra_fixture); | ||
443 | let url = analysis.external_docs(position).unwrap().expect("could not find url for symbol"); | ||
444 | |||
445 | expect.assert_eq(&url) | ||
446 | } | ||
447 | |||
448 | #[test] | ||
449 | fn test_doc_url_struct() { | ||
450 | check( | ||
451 | r#" | ||
452 | pub struct Fo<|>o; | ||
453 | "#, | ||
454 | expect![[r#"https://docs.rs/test/*/test/struct.Foo.html"#]], | ||
455 | ); | ||
456 | } | ||
457 | |||
458 | #[test] | ||
459 | fn test_doc_url_fn() { | ||
460 | check( | ||
461 | r#" | ||
462 | pub fn fo<|>o() {} | ||
463 | "#, | ||
464 | expect![[r##"https://docs.rs/test/*/test/fn.foo.html#method.foo"##]], | ||
465 | ); | ||
466 | } | ||
467 | |||
468 | #[test] | ||
469 | fn test_doc_url_inherent_method() { | ||
470 | check( | ||
471 | r#" | ||
472 | pub struct Foo; | ||
473 | |||
474 | impl Foo { | ||
475 | pub fn met<|>hod() {} | ||
476 | } | ||
477 | |||
478 | "#, | ||
479 | expect![[r##"https://docs.rs/test/*/test/struct.Foo.html#method.method"##]], | ||
480 | ); | ||
481 | } | ||
482 | |||
483 | #[test] | ||
484 | fn test_doc_url_trait_provided_method() { | ||
485 | check( | ||
486 | r#" | ||
487 | pub trait Bar { | ||
488 | fn met<|>hod() {} | ||
489 | } | ||
490 | |||
491 | "#, | ||
492 | expect![[r##"https://docs.rs/test/*/test/trait.Bar.html#method.method"##]], | ||
493 | ); | ||
494 | } | ||
495 | |||
496 | #[test] | ||
497 | fn test_doc_url_trait_required_method() { | ||
498 | check( | ||
499 | r#" | ||
500 | pub trait Foo { | ||
501 | fn met<|>hod(); | ||
502 | } | ||
503 | |||
504 | "#, | ||
505 | expect![[r##"https://docs.rs/test/*/test/trait.Foo.html#tymethod.method"##]], | ||
506 | ); | ||
507 | } | ||
508 | |||
509 | #[test] | ||
510 | fn test_doc_url_field() { | ||
511 | check( | ||
512 | r#" | ||
513 | pub struct Foo { | ||
514 | pub fie<|>ld: () | ||
515 | } | ||
516 | |||
517 | "#, | ||
518 | expect![[r##"https://docs.rs/test/*/test/struct.Foo.html#structfield.field"##]], | ||
519 | ); | ||
520 | } | ||
521 | |||
522 | // FIXME: ImportMap will return re-export paths instead of public module | ||
523 | // paths. The correct path to documentation will never be a re-export. | ||
524 | // This problem stops us from resolving stdlib items included in the prelude | ||
525 | // such as `Option::Some` correctly. | ||
526 | #[ignore = "ImportMap may return re-exports"] | ||
527 | #[test] | ||
528 | fn test_reexport_order() { | ||
529 | check( | ||
530 | r#" | ||
531 | pub mod wrapper { | ||
532 | pub use module::Item; | ||
533 | |||
534 | pub mod module { | ||
535 | pub struct Item; | ||
536 | } | ||
537 | } | ||
538 | |||
539 | fn foo() { | ||
540 | let bar: wrapper::It<|>em; | ||
541 | } | ||
542 | "#, | ||
543 | expect![[r#"https://docs.rs/test/*/test/wrapper/module/struct.Item.html"#]], | ||
544 | ) | ||
545 | } | ||
546 | } | ||
diff --git a/crates/ide/src/hover.rs b/crates/ide/src/hover.rs index 53265488e..6290b35bd 100644 --- a/crates/ide/src/hover.rs +++ b/crates/ide/src/hover.rs | |||
@@ -14,7 +14,7 @@ use test_utils::mark; | |||
14 | 14 | ||
15 | use crate::{ | 15 | use crate::{ |
16 | display::{macro_label, ShortLabel, ToNav, TryToNav}, | 16 | display::{macro_label, ShortLabel, ToNav, TryToNav}, |
17 | link_rewrite::{remove_links, rewrite_links}, | 17 | doc_links::{remove_links, rewrite_links}, |
18 | markdown_remove::remove_markdown, | 18 | markdown_remove::remove_markdown, |
19 | markup::Markup, | 19 | markup::Markup, |
20 | runnables::runnable, | 20 | runnables::runnable, |
diff --git a/crates/ide/src/lib.rs b/crates/ide/src/lib.rs index d54c06b14..686cee3a1 100644 --- a/crates/ide/src/lib.rs +++ b/crates/ide/src/lib.rs | |||
@@ -45,8 +45,8 @@ mod status; | |||
45 | mod syntax_highlighting; | 45 | mod syntax_highlighting; |
46 | mod syntax_tree; | 46 | mod syntax_tree; |
47 | mod typing; | 47 | mod typing; |
48 | mod link_rewrite; | ||
49 | mod markdown_remove; | 48 | mod markdown_remove; |
49 | mod doc_links; | ||
50 | 50 | ||
51 | use std::sync::Arc; | 51 | use std::sync::Arc; |
52 | 52 | ||
@@ -384,6 +384,14 @@ impl Analysis { | |||
384 | self.with_db(|db| hover::hover(db, position, links_in_hover, markdown)) | 384 | self.with_db(|db| hover::hover(db, position, links_in_hover, markdown)) |
385 | } | 385 | } |
386 | 386 | ||
387 | /// Return URL(s) for the documentation of the symbol under the cursor. | ||
388 | pub fn external_docs( | ||
389 | &self, | ||
390 | position: FilePosition, | ||
391 | ) -> Cancelable<Option<doc_links::DocumentationLink>> { | ||
392 | self.with_db(|db| doc_links::external_docs(db, &position)) | ||
393 | } | ||
394 | |||
387 | /// Computes parameter information for the given call expression. | 395 | /// Computes parameter information for the given call expression. |
388 | pub fn call_info(&self, position: FilePosition) -> Cancelable<Option<CallInfo>> { | 396 | pub fn call_info(&self, position: FilePosition) -> Cancelable<Option<CallInfo>> { |
389 | self.with_db(|db| call_info::call_info(db, position)) | 397 | self.with_db(|db| call_info::call_info(db, position)) |