https://github.com/hywan/code-tour-rs

Enhanced example-based learning, i.e. awesome example user experience
https://github.com/hywan/code-tour-rs

documentation example rust rust-lang user-experience

Last synced: 3 months ago
JSON representation

Enhanced example-based learning, i.e. awesome example user experience

• Host: GitHub
• URL: https://github.com/hywan/code-tour-rs
• Owner: Hywan
• License: bsd-3-clause
• Created: 2020-07-20T15:39:30.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2020-10-11T09:27:32.000Z (over 4 years ago)
• Last Synced: 2024-10-17T15:43:45.332Z (3 months ago)
• Topics: documentation, example, rust, rust-lang, user-experience
• Language: Rust
• Homepage:
• Size: 119 KB
• Stars: 23
• Watchers: 5
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE.md

Awesome Lists containing this project

README

        


  


  Code Tour



## Introduction

This project is an attempt to improve Rust example-based learning

approach.

Imagine the following example file:

```rust

#[derive(Debug)]

struct S {

    x: i32,

    y: i32,

}

fn main() {

    // Declare something.

    // Because it's an example.

    let a = S { x: 7, y: 42 };

    let b = a.x + a.y;

    // Here is the result!

    let c = b + 1;

}

```

When one runs the example with `cargo run --example foo`, nothing is

printed!  It means the author of the example must add `println!` or

`dbg!` instructions everytime. Moreover the users are going to miss

the comments, that's really unfortunate.

**Enter `code_tour`**.

Let's rewrite the example as such:

```rust

use code_tour::code_tour;

#[derive(Debug)]

struct S {

    x: i32,

    y: i32,

}

#[code_tour]

fn main() {

    /// Declare something.

    /// Because it's an example.

    let a = S { x: 7, y: 42 };

    let b = a.x + a.y;

    /// Here is the result!

    let c = b + 1;

}

```

Let's re-execute the example as previously, and we'll see:

```rust

$ cargo run --example foo

```

![cargo run example](./doc/cargo_run_example.png)

The example annotations are replicated on the output during the

execution.

An annotation must be a comment of kind `///` or `/** … */` that

introduces a `let` binding. That's all for the moment!

### Interactive mode

Running the example with `--features interactive` will display a

“Press Enter to continue, otherwise Ctrl-C to exit.” message after

each step of your code.

```rust

$ cargo run --example foo --features interactive

```

![cargo run example interactive](./doc/cargo_run_example_interactive.png)

### Quiet mode

Running the example with the environment variable `CODE_TOUR_QUIET`

set will turn code-tour silent. Note that it won't disable the

interactive mode (which is on purpose).

```rust

$ CODE_TOUR_QUIET=1 cargo run --example foo

```

### Better source code display

Running the example with `cargo +nightly` will generate a better

output for the code, by using

[`Span::source_text`](https://doc.rust-lang.org/proc_macro/struct.Span.html#method.source_text).

```rust

$ cargo +nightly run --example foo

```

## Install

This is a classic Rust project, thus add `code-tour` to your

`Cargo.toml` file, and that's it.

## License

`BSD-3-Clause`, see `LICENSE.md`.