diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/dev/README.md | 3 | ||||
-rw-r--r-- | docs/dev/lsp-extensions.md | 16 | ||||
-rw-r--r-- | docs/dev/style.md | 11 | ||||
-rw-r--r-- | docs/user/manual.adoc | 74 |
4 files changed, 73 insertions, 31 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md index d0e6d29d8..7e4488a41 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md | |||
@@ -242,6 +242,9 @@ There are three sets of people with extra permissions: | |||
242 | They also have direct commit access, but all changes should via bors queue. | 242 | They also have direct commit access, but all changes should via bors queue. |
243 | It's ok to self-approve if you think you know what you are doing! | 243 | It's ok to self-approve if you think you know what you are doing! |
244 | bors should automatically sync the permissions. | 244 | bors should automatically sync the permissions. |
245 | Feel free to request a review or assign any PR to a reviewer with the relevant expertise to bring the work to their attention. | ||
246 | Don't feel pressured to review assigned PRs though. | ||
247 | If you don't feel like reviewing for whatever reason, someone else will pick the review up! | ||
245 | * [**triage**](https://github.com/orgs/rust-analyzer/teams/triage) team in the organization. | 248 | * [**triage**](https://github.com/orgs/rust-analyzer/teams/triage) team in the organization. |
246 | This team can label and close issues. | 249 | This team can label and close issues. |
247 | 250 | ||
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md index a4d92242b..f0f981802 100644 --- a/docs/dev/lsp-extensions.md +++ b/docs/dev/lsp-extensions.md | |||
@@ -1,5 +1,5 @@ | |||
1 | <!--- | 1 | <!--- |
2 | lsp_ext.rs hash: b19ddc3ab8767af9 | 2 | lsp_ext.rs hash: 28a9d5a24b7ca396 |
3 | 3 | ||
4 | If you need to change the above hash to make the test pass, please check if you | 4 | If you need to change the above hash to make the test pass, please check if you |
5 | need to adjust this doc as well and ping this issue: | 5 | need to adjust this doc as well and ping this issue: |
@@ -46,6 +46,7 @@ If this capability is set, `WorkspaceEdit`s returned from `codeAction` requests | |||
46 | ```typescript | 46 | ```typescript |
47 | interface SnippetTextEdit extends TextEdit { | 47 | interface SnippetTextEdit extends TextEdit { |
48 | insertTextFormat?: InsertTextFormat; | 48 | insertTextFormat?: InsertTextFormat; |
49 | annotationId?: ChangeAnnotationIdentifier; | ||
49 | } | 50 | } |
50 | ``` | 51 | ``` |
51 | 52 | ||
@@ -421,7 +422,7 @@ Reloads project information (that is, re-executes `cargo metadata`). | |||
421 | 422 | ||
422 | ## Server Status | 423 | ## Server Status |
423 | 424 | ||
424 | **Experimental Client Capability:** `{ "serverStatus": boolean }` | 425 | **Experimental Client Capability:** `{ "serverStatusNotification": boolean }` |
425 | 426 | ||
426 | **Method:** `experimental/serverStatus` | 427 | **Method:** `experimental/serverStatus` |
427 | 428 | ||
@@ -432,11 +433,13 @@ interface ServerStatusParams { | |||
432 | /// `ok` means that the server is completely functional. | 433 | /// `ok` means that the server is completely functional. |
433 | /// | 434 | /// |
434 | /// `warning` means that the server is partially functional. | 435 | /// `warning` means that the server is partially functional. |
435 | /// It can server requests, but some results might be wrong due to, | 436 | /// It can answer correctly to most requests, but some results |
436 | /// for example, some missing dependencies. | 437 | /// might be wrong due to, for example, some missing dependencies. |
437 | /// | 438 | /// |
438 | /// `error` means that the server is not functional. For example, | 439 | /// `error` means that the server is not functional. For example, |
439 | /// there's a fatal build configuration problem. | 440 | /// there's a fatal build configuration problem. The server might |
441 | /// still give correct answers to simple requests, but most results | ||
442 | /// will be incomplete or wrong. | ||
440 | health: "ok" | "warning" | "error", | 443 | health: "ok" | "warning" | "error", |
441 | /// Is there any pending background work which might change the status? | 444 | /// Is there any pending background work which might change the status? |
442 | /// For example, are dependencies being downloaded? | 445 | /// For example, are dependencies being downloaded? |
@@ -450,6 +453,9 @@ This notification is sent from server to client. | |||
450 | The client can use it to display *persistent* status to the user (in modline). | 453 | The client can use it to display *persistent* status to the user (in modline). |
451 | It is similar to the `showMessage`, but is intended for stares rather than point-in-time events. | 454 | It is similar to the `showMessage`, but is intended for stares rather than point-in-time events. |
452 | 455 | ||
456 | Note that this functionality is intended primarily to inform the end user about the state of the server. | ||
457 | In particular, it's valid for the client to completely ignore this extension. | ||
458 | Clients are discouraged from but are allowed to use the `health` status to decide if it's worth sending a request to the server. | ||
453 | 459 | ||
454 | ## Syntax Tree | 460 | ## Syntax Tree |
455 | 461 | ||
diff --git a/docs/dev/style.md b/docs/dev/style.md index 078c478d4..6ab60b50e 100644 --- a/docs/dev/style.md +++ b/docs/dev/style.md | |||
@@ -83,8 +83,19 @@ This makes it easier to prepare a changelog. | |||
83 | 83 | ||
84 | If the change adds a new user-visible functionality, consider recording a GIF with [peek](https://github.com/phw/peek) and pasting it into the PR description. | 84 | If the change adds a new user-visible functionality, consider recording a GIF with [peek](https://github.com/phw/peek) and pasting it into the PR description. |
85 | 85 | ||
86 | To make writing the release notes easier, you can mark a pull request as a feature, fix, internal change, or minor. | ||
87 | Minor changes are excluded from the release notes, while the other types are distributed in their corresponding sections. | ||
88 | There are two ways to mark this: | ||
89 | |||
90 | * use a `feat: `, `feature: `, `fix: `, `internal: ` or `minor: ` prefix in the PR title | ||
91 | * write `changelog [feature|fix|internal|skip] [description]` in a comment or in the PR description; the description is optional, and will replace the title if included. | ||
92 | |||
93 | These comments don't have to be added by the PR author. | ||
94 | Editing a comment or the PR description or title is also fine, as long as it happens before the release. | ||
95 | |||
86 | **Rationale:** clean history is potentially useful, but rarely used. | 96 | **Rationale:** clean history is potentially useful, but rarely used. |
87 | But many users read changelogs. | 97 | But many users read changelogs. |
98 | Including a description and GIF suitable for the changelog means less work for the maintainers on the release day. | ||
88 | 99 | ||
89 | ## Clippy | 100 | ## Clippy |
90 | 101 | ||
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc index b86e91772..54195adb7 100644 --- a/docs/user/manual.adoc +++ b/docs/user/manual.adoc | |||
@@ -429,24 +429,32 @@ However, if you use some other build system, you'll have to describe the structu | |||
429 | [source,TypeScript] | 429 | [source,TypeScript] |
430 | ---- | 430 | ---- |
431 | interface JsonProject { | 431 | interface JsonProject { |
432 | /// Path to the directory with *source code* of sysroot crates. | 432 | /// Path to the directory with *source code* of |
433 | /// sysroot crates. | ||
434 | /// | ||
435 | /// It should point to the directory where std, | ||
436 | /// core, and friends can be found: | ||
433 | /// | 437 | /// |
434 | /// It should point to the directory where std, core, and friends can be found: | ||
435 | /// https://github.com/rust-lang/rust/tree/master/library. | 438 | /// https://github.com/rust-lang/rust/tree/master/library. |
436 | /// | 439 | /// |
437 | /// If provided, rust-analyzer automatically adds dependencies on sysroot | 440 | /// If provided, rust-analyzer automatically adds |
438 | /// crates. Conversely, if you omit this path, you can specify sysroot | 441 | /// dependencies on sysroot crates. Conversely, |
439 | /// dependencies yourself and, for example, have several different "sysroots" in | 442 | /// if you omit this path, you can specify sysroot |
440 | /// one graph of crates. | 443 | /// dependencies yourself and, for example, have |
444 | /// several different "sysroots" in one graph of | ||
445 | /// crates. | ||
441 | sysroot_src?: string; | 446 | sysroot_src?: string; |
442 | /// The set of crates comprising the current project. | 447 | /// The set of crates comprising the current |
443 | /// Must include all transitive dependencies as well as sysroot crate (libstd, libcore and such). | 448 | /// project. Must include all transitive |
449 | /// dependencies as well as sysroot crate (libstd, | ||
450 | /// libcore and such). | ||
444 | crates: Crate[]; | 451 | crates: Crate[]; |
445 | } | 452 | } |
446 | 453 | ||
447 | interface Crate { | 454 | interface Crate { |
448 | /// Optional crate name used for display purposes, without affecting semantics. | 455 | /// Optional crate name used for display purposes, |
449 | /// See the `deps` key for semantically-significant crate names. | 456 | /// without affecting semantics. See the `deps` |
457 | /// key for semantically-significant crate names. | ||
450 | display_name?: string; | 458 | display_name?: string; |
451 | /// Path to the root module of the crate. | 459 | /// Path to the root module of the crate. |
452 | root_module: string; | 460 | root_module: string; |
@@ -454,45 +462,59 @@ interface Crate { | |||
454 | edition: "2015" | "2018" | "2021"; | 462 | edition: "2015" | "2018" | "2021"; |
455 | /// Dependencies | 463 | /// Dependencies |
456 | deps: Dep[]; | 464 | deps: Dep[]; |
457 | /// Should this crate be treated as a member of current "workspace". | 465 | /// Should this crate be treated as a member of |
466 | /// current "workspace". | ||
458 | /// | 467 | /// |
459 | /// By default, inferred from the `root_module` (members are the crates which reside | 468 | /// By default, inferred from the `root_module` |
460 | /// inside the directory opened in the editor). | 469 | /// (members are the crates which reside inside |
470 | /// the directory opened in the editor). | ||
461 | /// | 471 | /// |
462 | /// Set this to `false` for things like standard library and 3rd party crates to | 472 | /// Set this to `false` for things like standard |
463 | /// enable performance optimizations (rust-analyzer assumes that non-member crates | 473 | /// library and 3rd party crates to enable |
464 | /// don't change). | 474 | /// performance optimizations (rust-analyzer |
475 | /// assumes that non-member crates don't change). | ||
465 | is_workspace_member?: boolean; | 476 | is_workspace_member?: boolean; |
466 | /// Optionally specify the (super)set of `.rs` files comprising this crate. | 477 | /// Optionally specify the (super)set of `.rs` |
478 | /// files comprising this crate. | ||
467 | /// | 479 | /// |
468 | /// By default, rust-analyzer assumes that only files under `root_module.parent` can belong to a crate. | 480 | /// By default, rust-analyzer assumes that only |
469 | /// `include_dirs` are included recursively, unless a subdirectory is in `exclude_dirs`. | 481 | /// files under `root_module.parent` can belong |
482 | /// to a crate. `include_dirs` are included | ||
483 | /// recursively, unless a subdirectory is in | ||
484 | /// `exclude_dirs`. | ||
470 | /// | 485 | /// |
471 | /// Different crates can share the same `source`. | 486 | /// Different crates can share the same `source`. |
472 | /// | 487 | /// |
473 | /// If two crates share an `.rs` file in common, they *must* have the same `source`. | 488 | /// If two crates share an `.rs` file in common, |
474 | /// rust-analyzer assumes that files from one source can't refer to files in another source. | 489 | /// they *must* have the same `source`. |
490 | /// rust-analyzer assumes that files from one | ||
491 | /// source can't refer to files in another source. | ||
475 | source?: { | 492 | source?: { |
476 | include_dirs: string[], | 493 | include_dirs: string[], |
477 | exclude_dirs: string[], | 494 | exclude_dirs: string[], |
478 | }, | 495 | }, |
479 | /// The set of cfgs activated for a given crate, like `["unix", "feature=\"foo\"", "feature=\"bar\""]`. | 496 | /// The set of cfgs activated for a given crate, like |
497 | /// `["unix", "feature=\"foo\"", "feature=\"bar\""]`. | ||
480 | cfg: string[]; | 498 | cfg: string[]; |
481 | /// Target triple for this Crate. | 499 | /// Target triple for this Crate. |
482 | /// | 500 | /// |
483 | /// Used when running `rustc --print cfg` to get target-specific cfgs. | 501 | /// Used when running `rustc --print cfg` |
502 | /// to get target-specific cfgs. | ||
484 | target?: string; | 503 | target?: string; |
485 | /// Environment variables, used for the `env!` macro | 504 | /// Environment variables, used for |
505 | /// the `env!` macro | ||
486 | env: : { [key: string]: string; }, | 506 | env: : { [key: string]: string; }, |
487 | 507 | ||
488 | /// For proc-macro crates, path to compiles proc-macro (.so file). | 508 | /// For proc-macro crates, path to compiled |
509 | /// proc-macro (.so file). | ||
489 | proc_macro_dylib_path?: string; | 510 | proc_macro_dylib_path?: string; |
490 | } | 511 | } |
491 | 512 | ||
492 | interface Dep { | 513 | interface Dep { |
493 | /// Index of a crate in the `crates` array. | 514 | /// Index of a crate in the `crates` array. |
494 | crate: number, | 515 | crate: number, |
495 | /// Name as should appear in the (implicit) `extern crate name` declaration. | 516 | /// Name as should appear in the (implicit) |
517 | /// `extern crate name` declaration. | ||
496 | name: string, | 518 | name: string, |
497 | } | 519 | } |
498 | ---- | 520 | ---- |