From 71a6041edfa14bfb66732c3b397a735e4d667ec3 Mon Sep 17 00:00:00 2001 From: olivia Date: Tue, 22 May 2018 20:59:50 +0200 Subject: [PATCH] add some basic docs --- README.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/README.md b/README.md index bcd03a95..2a514119 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,39 @@ A cool thing that is currently in development. +## How it's structured + +Ideally, like RubyKoans, all exercises can be run by executing one command, in this case +`cargo run` (most likely). This runs `src/main.rs`, which in turn runs all of the exercises. +Each exercise is contained in a Rust file called `about_.rs`. A minimal exercise looks +somewhat like this: + +```rust +fn exercise_function() { + "hello" +} + +mod tests { + use super::*; + + pub fn test() { + verify!("REPLACE ME", exercise_function(), "Function description"); + } +} + +pub fn exec() { + tests::test(); +} +``` + +Each exercise file is supposed to have one `exec` function which gets called by the `main.rs` file. +This function, in turn, calls all individual test functions. + +The tests themselves can generally be structured in whatever way is desired. Two macros are provided +for convenience. The `verify!` macro is essentially a specialized `assert_eq!`, but it doesn't panic +if the values mismatch, instead it prints out a helpful error message and keeps going. The +`verify_easy!` macro is designed as a drop-in replacement for the `verify!` macro for if the learner needs help solving the exercise. It prints the expected value, too. + +Keep in mind that this is a very early draft of how things work. Anything here might be changed +at any time, and this documentation should be updated accordingly. +