Write README

Author: omus

README.md

@@ -5,3 +5,50 @@
 [![Build Status](https://travis-ci.com/invenia/MultilineStrings.jl.svg?branch=master)](https://travis-ci.com/invenia/MultilineStrings.jl)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+
+Tooling for manipulating multiline strings.
+
+## Features
+
+The package features the `@m_str` macro, inspired from [YAML's block scalars](https://yaml-multiline.info/), which provide options for manipulating multiline strings via a style and chomp indicator:
+
+- Style indicator:
+    - `f` replace newlines with spaces (folded)
+    - `l` keep newlines (literal)
+- Chomp indicator:
+    - `s` no newlines at the end (strip)
+    - `c` single newline at the end (clip)
+    - `k` keep all newlines from the end (keep)
+
+The indicators are provided after the ending quote of the string (e.g. `m"hello\nworld!"fc`).
+If no indicators are provided the default behaviour is folded/strip.
+
+## Example
+
+When writing a long string literal you may want to break the string up over multiple lines in the code, to make it easier to read, but have the string be printed as a single line.
+Specifically, when writing an long error message you may want to break up the string over multiple lines:
+
+```julia
+"An unexpected error has occurred which really shouldn't have happened but somehow did. Please check that the inputs to this function doesn't contain magic that may interfere with with the non-magical computation occurring on this device."
+```
+
+Alternatively written over multiple lines:
+
+```julia
+"An unexpected error has occurred which really shouldn't " *
+"have happened but somehow did. Please check that the inputs " *
+"to this function doesn't contain magic that may interfere with " *
+"with the non-magical computation occurring on this device."
+```
+
+Writing strings this way can be cumbersome as you need to remember to add spaces between each line.
+The MultilineStrings package provides an alternative way of writing this using the multiline string macro:
+
+```julia
+m"""
+An unexpected error has occurred which really shouldn't
+have happened but somehow did. Please check that the inputs
+to this function doesn't contain magic that may interfere with
+with the non-magical computation occurring on this device.
+"""
+```

src/MultilineStrings.jl

@@ -180,16 +180,29 @@ end
 """
     @m_str -> String
 
-Construct a multiline string according to the indicators listed after the ending quote:
+Construct a multiline string according to a style and chomp indicators (provided after the
+ending quote):
 
-- `f` replace newlines with spaces (folded)
-- `l` keep newlines (literal)
-- `s` no newlines at the end (strip)
-- `c` single newline at the end (clip)
-- `k` keep all newlines from the end (keep)
+- Style indicator:
+    - `f` replace newlines with spaces (folded)
+    - `l` keep newlines (literal)
+- Chomp indicator:
+    - `s` no newlines at the end (strip)
+    - `c` single newline at the end (clip)
+    - `k` keep all newlines from the end (keep)
 
 Note string interpolation is still respected any newlines added from interpolation will be
 also be processed.
+
+# Examples
+
+```jldoctest; setup = :(using MultilineStrings)
+julia> m\"\"\"
+       A string written
+       over multiple lines
+       \"\"\"
+"A string written over multiple lines"
+```
 """
 macro m_str(str::AbstractString, indicators::AbstractString="")
     parsed = interpolate(str)