From 8a5d14453e464edeb8613df2fdca742bfe2a72f5 Mon Sep 17 00:00:00 2001
From: Timo Freiberg <timo.freiberg@gmail.com>
Date: Tue, 5 May 2020 23:36:35 +0200
Subject: Add fixture doc comment
---
crates/ra_db/src/fixture.rs | 46 ++++++++++++++++++++++++++++++++++++++++++++-
xtask/tests/tidy.rs | 1 -
2 files changed, 45 insertions(+), 2 deletions(-)
diff --git a/crates/ra_db/src/fixture.rs b/crates/ra_db/src/fixture.rs
index 8248684ee..51d4c493e 100644
--- a/crates/ra_db/src/fixture.rs
+++ b/crates/ra_db/src/fixture.rs
@@ -1,4 +1,48 @@
-//! FIXME: write short doc here
+//! 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.
+//!
+//! 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:
+//! ```
+//! "
+//! //- /main.rs
+//! mod foo;
+//! fn main() {
+//! foo::bar();
+//! }
+//!
+//! //- /foo.rs
+//! pub fn bar() {}
+//! "
+//! ```
+//!
+//! 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:
+//! ```
+//! "
+//! //- /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::str::FromStr;
use std::sync::Arc;
diff --git a/xtask/tests/tidy.rs b/xtask/tests/tidy.rs
index c4eac1bc4..b8e8860ba 100644
--- a/xtask/tests/tidy.rs
+++ b/xtask/tests/tidy.rs
@@ -136,7 +136,6 @@ impl TidyDocs {
}
let whitelist = [
- "ra_db",
"ra_hir",
"ra_hir_expand",
"ra_ide",
--
cgit v1.2.3