Skip to content

Commit 45f61cc

Browse files
committed
docs(test): Expand docs for Project
1 parent 3dff0ec commit 45f61cc

File tree

1 file changed

+55
-19
lines changed
  • crates/cargo-test-support/src

1 file changed

+55
-19
lines changed

crates/cargo-test-support/src/lib.rs

Lines changed: 55 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -243,12 +243,16 @@ pub struct ProjectBuilder {
243243
}
244244

245245
impl ProjectBuilder {
246-
/// Root of the project, ex: `/path/to/cargo/target/cit/t0/foo`
246+
/// Root of the project
247+
///
248+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo`
247249
pub fn root(&self) -> PathBuf {
248250
self.root.root()
249251
}
250252

251-
/// Project's debug dir, ex: `/path/to/cargo/target/cit/t0/foo/target/debug`
253+
/// Project's debug dir
254+
///
255+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo/target/debug`
252256
pub fn target_debug_dir(&self) -> PathBuf {
253257
self.root.target_debug_dir()
254258
}
@@ -366,54 +370,67 @@ impl Project {
366370
Self { root: project_root }
367371
}
368372

369-
/// Root of the project, ex: `/path/to/cargo/target/cit/t0/foo`
373+
/// Root of the project
374+
///
375+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo`
370376
pub fn root(&self) -> PathBuf {
371377
self.root.clone()
372378
}
373379

374-
/// Project's target dir, ex: `/path/to/cargo/target/cit/t0/foo/target`
380+
/// Project's target dir
381+
///
382+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo/target`
375383
pub fn build_dir(&self) -> PathBuf {
376384
self.root().join("target")
377385
}
378386

379-
/// Project's debug dir, ex: `/path/to/cargo/target/cit/t0/foo/target/debug`
387+
/// Project's debug dir
388+
///
389+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo/target/debug`
380390
pub fn target_debug_dir(&self) -> PathBuf {
381391
self.build_dir().join("debug")
382392
}
383393

384-
/// File url for root, ex: `file:///path/to/cargo/target/cit/t0/foo`
394+
/// File url for root
395+
///
396+
/// ex: `file://$CARGO_TARGET_TMPDIR/cit/t0/foo`
385397
pub fn url(&self) -> Url {
386398
use paths::CargoPathExt;
387399
self.root().to_url()
388400
}
389401

390402
/// Path to an example built as a library.
403+
///
391404
/// `kind` should be one of: "lib", "rlib", "staticlib", "dylib", "proc-macro"
392-
/// ex: `/path/to/cargo/target/cit/t0/foo/target/debug/examples/libex.rlib`
405+
///
406+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo/target/debug/examples/libex.rlib`
393407
pub fn example_lib(&self, name: &str, kind: &str) -> PathBuf {
394408
self.target_debug_dir()
395409
.join("examples")
396410
.join(paths::get_lib_filename(name, kind))
397411
}
398412

399413
/// Path to a debug binary.
400-
/// ex: `/path/to/cargo/target/cit/t0/foo/target/debug/foo`
414+
///
415+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo/target/debug/foo`
401416
pub fn bin(&self, b: &str) -> PathBuf {
402417
self.build_dir()
403418
.join("debug")
404419
.join(&format!("{}{}", b, env::consts::EXE_SUFFIX))
405420
}
406421

407422
/// Path to a release binary.
408-
/// ex: `/path/to/cargo/target/cit/t0/foo/target/release/foo`
423+
///
424+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo/target/release/foo`
409425
pub fn release_bin(&self, b: &str) -> PathBuf {
410426
self.build_dir()
411427
.join("release")
412428
.join(&format!("{}{}", b, env::consts::EXE_SUFFIX))
413429
}
414430

415431
/// Path to a debug binary for a specific target triple.
416-
/// ex: `/path/to/cargo/target/cit/t0/foo/target/i686-apple-darwin/debug/foo`
432+
///
433+
/// ex: `$CARGO_TARGET_TMPDIR/cit/t0/foo/target/i686-apple-darwin/debug/foo`
417434
pub fn target_bin(&self, target: &str, b: &str) -> PathBuf {
418435
self.build_dir().join(target).join("debug").join(&format!(
419436
"{}{}",
@@ -422,35 +439,54 @@ impl Project {
422439
))
423440
}
424441

425-
/// Returns an iterator of paths matching the glob pattern, which is
426-
/// relative to the project root.
442+
/// Returns an iterator of paths within [`Project::root`] matching the glob pattern
427443
pub fn glob<P: AsRef<Path>>(&self, pattern: P) -> glob::Paths {
428444
let pattern = self.root().join(pattern);
429445
glob::glob(pattern.to_str().expect("failed to convert pattern to str"))
430446
.expect("failed to glob")
431447
}
432448

433-
/// Changes the contents of an existing file.
449+
/// Overwrite a file with new content
450+
///
451+
// # Example:
452+
///
453+
/// ```no_run
454+
/// # let p = cargo_test_support::project().build();
455+
/// p.change_file("src/lib.rs", "fn new_fn() {}");
456+
/// ```
434457
pub fn change_file(&self, path: &str, body: &str) {
435458
FileBuilder::new(self.root().join(path), body, false).mk()
436459
}
437460

438461
/// Creates a `ProcessBuilder` to run a program in the project
439462
/// and wrap it in an Execs to assert on the execution.
440-
/// Example:
441-
/// p.process(&p.bin("foo"))
442-
/// .with_stdout("bar\n")
443-
/// .run();
463+
///
464+
/// # Example:
465+
///
466+
/// ```no_run
467+
/// # let p = cargo_test_support::project().build();
468+
/// p.process(&p.bin("foo"))
469+
/// .with_stdout("bar\n")
470+
/// .run();
471+
/// ```
444472
pub fn process<T: AsRef<OsStr>>(&self, program: T) -> Execs {
445473
let mut p = process(program);
446474
p.cwd(self.root());
447475
execs().with_process_builder(p)
448476
}
449477

450478
/// Creates a `ProcessBuilder` to run cargo.
479+
///
451480
/// Arguments can be separated by spaces.
452-
/// Example:
453-
/// p.cargo("build --bin foo").run();
481+
///
482+
/// For `cargo run`, see [`Project::rename_run`].
483+
///
484+
/// # Example:
485+
///
486+
/// ```no_run
487+
/// # let p = cargo_test_support::project().build();
488+
/// p.cargo("build --bin foo").run();
489+
/// ```
454490
pub fn cargo(&self, cmd: &str) -> Execs {
455491
let cargo = cargo_exe();
456492
let mut execs = self.process(&cargo);

0 commit comments

Comments
 (0)