Improve documentation

README.md

 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
 

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")