More Travis, More Docs

Just to get this to a nice basic level of code quality.

.travis.yml

@@ -1 +1,34 @@
+sudo: false
 language: rust
+rust:
+- 1.8.0
+- stable
+- nightly
+before_script:
+- |
+  pip install 'travis-cargo<0.2' --user &&
+  export PATH=$HOME/.local/bin:$PATH
+script:
+- |
+  travis-cargo build &&
+  travis-cargo test &&
+  travis-cargo bench &&
+  travis-cargo --only stable doc
+addons:
+  apt:
+    packages:
+    - libcurl4-openssl-dev
+    - libelf-dev
+    - libdw-dev
+    - binutils-dev
+after_success:
+- travis-cargo --only stable doc-upload
+- travis-cargo coveralls --no-sudo
+notifications:
+  email:
+    on_success: never
+env:
+  global:
+  - TRAVIS_CARGO_NIGHTLY_FEATURE=""
+  - RUST_BACKTRACE=1
+  - secure: j6bdUXvEOUKMBNfFhycgWbGeMpb9eJwjTDzpa9gOD+6Olv96q/UPwM7WxfiFXywn6Rct+udZO/aPTt2JPFV0qnz/pwy+vk6zg3/mYqtCAmDkUMtWAm0eJNj9zMwT5KISc4BJb6TwCf0JdCVEPP4hLEAhNJEMRT1NCLQeFRoAjHe6plXHlNhWWdpffZxPjP9EP+JFKWv/Kr2NGxddiU4QFMEKHZEN9F+QAnQ9YGg4XzFB55cM53pk2wejbdbXfmUbS1/a8whqdb8nlGQuJ7j7MNuK7RXlDMXoYn27x/3SStnhzDUfVcUnwiRGcIEXAJalRaZAZbdlhjqi2kAmNbISZ8CiotxnD7ZLXkvApIqqNCE4xOvSFj5UPpl1GfsitpFWcvAt+2V0lpZ1S2IftLd88FG6b6zX1uAfiBZWwoOC5xShtBMTGF95I7jwIOHZzPFUEB+4Oys1WxxGp0DWwccL6tKrsvCswKRA66KibD9pCMp1kh1mOwJLiNMlu9rbFE5Llux1e2pCoj57F1Ag4WdTTGp88I8JwuqaIVchBGYshwS1ixG2wyKdMuy7dgqaVC5AqJA88aj7TA5gbHbKifpU0ihb6mmYDOSnLjlUNWMUMl8/sAyOt+7JmrWVRSn061CmtihrdGnWApVqa2mK4DL3/plmK++FsKSOI3VkKA0/GYA=

README.md

@@ -4,6 +4,13 @@ This is a **proof of concept**.
 
 This Rust library can be used to extract some data from documentation formatted as described [here](https://scribbles.pascalhertleif.de/machine-readable-inline-markdown-code-cocumentation.html).
 
+[![Build Status](https://travis-ci.org/killercup/rust-docstrings.svg?branch=master)](https://travis-ci.org/killercup/rust-docstrings)
+[![Coverage Status](https://coveralls.io/repos/github/killercup/rust-docstrings/badge.svg?branch=master)](https://coveralls.io/github/killercup/rust-docstrings?branch=master)
+
+[Rendered **Documentation** of master branch.](https://killercup.github.io/rust-docstrings/)
+
+## What it does
+
 For example, given a string like this one:
 
 ```markdown

src/errors.rs

@@ -2,17 +2,21 @@ quick_error! {
     /// Errors while parsing documention
     #[derive(Debug, PartialEq, Eq, Clone, Hash)]
     pub enum ParseError {
+        /// Missing teaser
         NoTeaser {
             description("Doc comment did not start with a teaser.")
         }
+        /// Unexpected markdown text
         UnexpectedMarkdown(section: String, event: String) {
             description("Unexpected Markdown")
             display("Unexpected Markdown in section `{sec}`: {event}",
                 sec=section, event=event)
         }
+        /// List not starting with an identifier (inline code)
         NoIdent {
             description("No identifier in list mapping ident -> docs")
         }
+        /// Invalid list formatting with identifier/docs
         WrongIdentDocsSeparator {
             description("List identifier and doc string must be written like this: `itend`: Docs")
         }

src/lib.rs

@@ -1,3 +1,11 @@
+//! Extract data from documentation strings.
+//!
+//! The expected format is described [here][1].
+//!
+//! [1]: https://scribbles.pascalhertleif.de/machine-readable-inline-markdown-code-cocumentation.html
+
+#![deny(missing_docs, warnings, unsafe_code, missing_debug_implementations)]
+
 extern crate pulldown_cmark;
 #[macro_use] extern crate quick_error;
 
@@ -8,9 +16,50 @@ mod errors;
 mod to_md;
 mod extractors;
 
-pub use ::errors::ParseError;
+pub use errors::ParseError;
 pub use types::*;
 
+/// Parse documentation and extract data
+///
+/// # Parameters
+///
+/// - `md`: Markdown string, needs to be parseable by `pulldown-cmark`
+///
+/// # Returns
+///
+/// A `Result`, which is either
+///
+/// - `Ok(DocBlock)`: A type that contains all extracted information (including
+///     all unknown sections as `Custom` sections).
+/// - `Err(ParseError)`: The first encountered error while parsing the
+///     documentation string.
+///
+/// # Examples
+///
+/// Please excuse the weird way the input is formatting in this example.
+/// Embedding Markdown strings in Rust code examples, which are just code blocks
+/// in Markdown documentation strings inside a Rust program is kinda hard:
+/// Rustdoc treads `#` at the beginning of code example line as a sign it
+/// should omit the line from output. Sadly, this means I can't write Markdown
+/// headlines as usual.
+///
+/// ```rust
+/// # use self::docstrings::*;
+/// assert_eq!(parse_md_docblock(
+///     "Lorem ipsum\n\nDolor sit amet.\n\n# Parameters\n\n- `param1`: Foo\n- `param2`: Bar\n"
+/// ).unwrap(),
+///     DocBlock {
+///         teaser: "Lorem ipsum".into(),
+///         description: Some("Dolor sit amet.".into()),
+///         sections: vec![
+///             DocSection::Parameters(vec![
+///                 ("param1".into(), "Foo".into()),
+///                 ("param2".into(), "Bar".into())
+///             ])
+///         ]
+///     }
+/// );
+/// ```
 pub fn parse_md_docblock(md: &str) -> Result<DocBlock, ParseError> {
     let mut md_events = Parser::new(md).peekable();