From e1cdee8d22036c14c493952145a741d3831fd4ad Mon Sep 17 00:00:00 2001
From: Phil <phil@grmr.de>
Date: Fri, 10 Nov 2017 20:05:07 +0100
Subject: [PATCH] Improve documentation

---
 README.md     | 36 +++++++++++++++++++++++++++++++-----
 src/parser.rs |  1 +
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 1d00e55..73fc9c4 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,39 @@
 Rust implementation of [golang challenge #1](http://golang-challenge.org/go-challenge1).
 
-A simple binary fileformat for a drum machine is given. The task is to reverse
+A simple binary file format for a drum machine is given. The task is to reverse
 it and implement a decoder it.
 
-## ToDo
+## File format
 
-- [ ] write example cli that pretty prints the fixture's contents
-- [ ] create documentation/tutorial/walkthrough and give it to `nom` community
-	- [ ] describt binary format (result of re)
+There is no real specification. But this is my understanding based on looking
+at the provided example files and reading the challenge description.
+
+A file starts with a header and is followed by multiple lines. All numbers are
+encoded with big endianness.
+
+### Header
+
+Size | encoding | Description
+-----|----------|------------
+ 6   | ASCII    | magic bytes "SPLICE"
+ 8   | u64      | file size (bytes _after_ this field are counted)
+32   | ASCII    | version string (of the editor used to create the file?)
+ 4   | f32      | tempo
+
+### Line
+
+Size | Encoding | Description
+-----|----------|----------------
+ 1   | u8       | id
+ 4   | u32      | length of the name field (n_l)
+ n   | ASCII    | name
+16   | bool[]   | data (encoded as information when to hit)
+
+## To-do
+
+- [ ] write example CLI that pretty prints the fixture's contents
+- [ ] create documentation / tutorial / walk through
 	- [ ] describe implementation steps
 	- [ ] maybe add something (tests!?) that allows for better/easier debugging
+		- [ ] find out how to properly debug
 
diff --git a/src/parser.rs b/src/parser.rs
index ea613c8..0c5997b 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -46,6 +46,7 @@ named!(parse_pattern<&[u8], Pattern>,
                 // ignore all unused bytes at the end
                 IResult::Done(_,pattern) => pattern,
                 // XXX: what type of input could trigger this?
+                //       -> uncommon values in file length?
                 // TODO: make it not panic and handle it gracefully
                 // TODO: add extra testcase, that triggers this path
                 _ => panic!("this should never be reached")
-- 
GitLab