Adjust fixture docs a bit

crates/base_db/src/fixture.rs

@@ -1,62 +1,4 @@
-//! Fixtures are strings containing rust source code with optional metadata.
+//! A set of high-level utility fixture methods to use in tests.
-//! A fixture without metadata is parsed into a single source file.
-//! Use this to test functionality local to one file.
-//!
-//! Simple Example:
-//! ```
-//! r#"
-//! fn main() {
-//!     println!("Hello World")
-//! }
-//! "#
-//! ```
-//!
-//! Metadata can be added to a fixture after a `//-` comment.
-//! The basic form is specifying filenames,
-//! which is also how to define multiple files in a single test fixture
-//!
-//! Example using two files in the same crate:
-//! ```
-//! "
-//! //- /main.rs
-//! mod foo;
-//! fn main() {
-//!     foo::bar();
-//! }
-//!
-//! //- /foo.rs
-//! pub fn bar() {}
-//! "
-//! ```
-//!
-//! Example using two crates with one file each, with one crate depending on the other:
-//! ```
-//! r#"
-//! //- /main.rs crate:a deps:b
-//! fn main() {
-//!     b::foo();
-//! }
-//! //- /lib.rs crate:b
-//! pub fn b() {
-//!     println!("Hello World")
-//! }
-//! "#
-//! ```
-//!
-//! Metadata allows specifying all settings and variables
-//! that are available in a real rust project:
-//! - crate names via `crate:cratename`
-//! - dependencies via `deps:dep1,dep2`
-//! - configuration settings via `cfg:dbg=false,opt_level=2`
-//! - environment variables via `env:PATH=/bin,RUST_LOG=debug`
-//!
-//! Example using all available metadata:
-//! ```
-//! "
-//! //- /lib.rs crate:foo deps:bar,baz cfg:foo=a,bar=b env:OUTDIR=path/to,OTHER=foo
-//! fn insert_source_code_here() {}
-//! "
-//! ```
 use std::{mem, str::FromStr, sync::Arc};
 
 use cfg::CfgOptions;

crates/test_utils/src/fixture.rs

@@ -1,5 +1,65 @@
 //! Defines `Fixture` -- a convenient way to describe the initial state of
 //! rust-analyzer database from a single string.
+//!
+//! Fixtures are strings containing rust source code with optional metadata.
+//! A fixture without metadata is parsed into a single source file.
+//! Use this to test functionality local to one file.
+//!
+//! Simple Example:
+//! ```
+//! r#"
+//! fn main() {
+//!     println!("Hello World")
+//! }
+//! "#
+//! ```
+//!
+//! Metadata can be added to a fixture after a `//-` comment.
+//! The basic form is specifying filenames,
+//! which is also how to define multiple files in a single test fixture
+//!
+//! Example using two files in the same crate:
+//! ```
+//! "
+//! //- /main.rs
+//! mod foo;
+//! fn main() {
+//!     foo::bar();
+//! }
+//!
+//! //- /foo.rs
+//! pub fn bar() {}
+//! "
+//! ```
+//!
+//! Example using two crates with one file each, with one crate depending on the other:
+//! ```
+//! r#"
+//! //- /main.rs crate:a deps:b
+//! fn main() {
+//!     b::foo();
+//! }
+//! //- /lib.rs crate:b
+//! pub fn b() {
+//!     println!("Hello World")
+//! }
+//! "#
+//! ```
+//!
+//! Metadata allows specifying all settings and variables
+//! that are available in a real rust project:
+//! - crate names via `crate:cratename`
+//! - dependencies via `deps:dep1,dep2`
+//! - configuration settings via `cfg:dbg=false,opt_level=2`
+//! - environment variables via `env:PATH=/bin,RUST_LOG=debug`
+//!
+//! Example using all available metadata:
+//! ```
+//! "
+//! //- /lib.rs crate:foo deps:bar,baz cfg:foo=a,bar=b env:OUTDIR=path/to,OTHER=foo
+//! fn insert_source_code_here() {}
+//! "
+//! ```
 
 use rustc_hash::FxHashMap;
 use stdx::{lines_with_ends, split_once, trim_indent};
@@ -24,7 +84,7 @@ impl Fixture {
     ///  //- some meta
     ///  line 1
     ///  line 2
-    ///  // - other meta
+    ///  //- other meta
     ///  ```
     pub fn parse(ra_fixture: &str) -> Vec<Fixture> {
         let fixture = trim_indent(ra_fixture);

docs/dev/architecture.md

@@ -390,7 +390,7 @@ fn spam() {
 ```
 
 To specify input data, we use a single string literal in a special format, which can describe a set of rust files.
-See the `Fixture` type.
+See the `Fixture` its module for fixture examples and documentation.
 
 **Architecture Invariant:** all code invariants are tested by `#[test]` tests.
 There's no additional checks in CI, formatting and tidy tests are run with `cargo test`.