Fixed readme and release

README.md

@@ -54,7 +54,7 @@ Contents
 * [Changelog](#changelog)
 
 <a name="getting-started"></a> Getting started
-------------------------------------------
+----------------------------------------------
 
 The library is published to the Maven central, so you can just add the following line
 to your `build.sbt` file in order to use the core library:
@@ -99,7 +99,7 @@ available later.
   [Jawn]: https://github.com/non/jawn
 
 <a name="serialization-mechanism"></a> Serialization mechanism
-----------------------------------------------------------
+--------------------------------------------------------------
 
 picopickle uses the pretty standard typeclass approach where the way the type is serialized
 or deserialized is defined through implicit objects (called `Reader[T]` and `Writer[T]` in picopickle)
@@ -136,7 +136,7 @@ picopickle also supports default values and variable arguments in case classes a
 or sealed trait descendants with a bit of custom macros.
 
 <a name="usage"></a> Usage
------
+--------------------------
 
 ### <a name="basic-usage"></a> Basic usage
 
@@ -546,7 +546,7 @@ val s: backend.BString = backend.makeString("hello world")
 These implicit methods are somewhat more convenient than `make*` functions.
 
 <a name="converters"></a> Converters
---------------------------------
+------------------------------------
 
 Low-level conversions, however, may be overly verbose to write. picopickle provides a declarative way of
 defining how the backend representation should be translated to the desired Scala objects and vice versa.
@@ -677,7 +677,7 @@ val optionStringConv: Converter.Id[Option[String]] = value[Option[String]]
 You can find more on converters in their Scaladoc section (**TODO**).
 
 <a name="supported-types"></a> Supported types
-------------------------------------------
+----------------------------------------------
 
 By default picopickle provides a lot of serializers for various types which do their
 best to represent their respective types in the serialized form as close as possible.
@@ -1141,7 +1141,7 @@ as a `BNumber` if it can be represented precisely in `Double` as a `BString` oth
 This trait is useful e.g. when writing a JSON-based backend.
 
 <a name="official-backends"></a> Official backends
-----------------------------------------------
+--------------------------------------------------
 
 ### <a name="collections-pickler"></a> Collections pickler
 
@@ -1295,7 +1295,7 @@ it serializes `BValue` as `BValue`, `BString` as `BString`, `BInt64` as `BInt64`
   [bson]: http://mongodb.github.io/mongo-java-driver/3.0/bson/
 
 <a name="error-handling"></a> Error handling
-----------------------------------------
+--------------------------------------------
 
 While serialization is straightforward and should never fail (if it does, it is most likely a bug in the library
 or in some `Writer` implementation), deserialization is prone to errors because the serialized representation usually
@@ -1384,7 +1384,7 @@ serialization methods, like Jawn's `tryReadString()`.
 
 
 <a name="limitations"></a> Limitations
-----------------------------------
+--------------------------------------
 
 picopickle does not support serializing `Any` in any form because it relies on the static knowledge of
 types being serialized. However, its design, as far as I can tell, in principle does not disallow writing
@@ -1434,16 +1434,17 @@ object Serializers {
 
 
 <a name="plans"></a> Plans
-----------------------
+--------------------------
 
 * Consider adding support for more types
 * Consider adding more converters (e.g. for tuples)
+* Add proper support for error handling in conversions
 * Add more tests
 * Add more documentation
 
 
 <a name="changelog"></a> Changelog
-------------------------------
+----------------------------------
 
 ### 0.2.0
 

notes/0.2.0.markdown

@@ -1,55 +1,53 @@
 This release contains a lot of changes and new features.
 
-* Updated shapeless to 2.3.3, jawn to 0.8.8, scala to 2.11.7.
+### Updated shapeless to 2.3.3, jawn to 0.8.8, scala to 2.11.7.
 
-  In particular, updating shapeless allowed using picopickle with case classes with variable arguments.
+In particular, updating shapeless allowed using picopickle with case classes with variable arguments.
 
-* Improved reader interface - added `readOrElse` method and changed existing code to depend on it.
+### Improved reader interface - added `readOrElse` method and changed existing code to depend on it.
 
-  `readOrElse` is borrowed from `PartialFunction` trait where it is called `applyOrElse`. It is an
-  important method for optimization because it allows checking whether a function (reader) can be
-  applied to a value and apply it to this value at the same time. Now `Reader` trait has this method
-  and it is defined and used correctly by the built-in `Reader` combinators, in particular,
-  for error checks.
+`readOrElse` is borrowed from `PartialFunction` trait where it is called `applyOrElse`. It is an
+important method for optimization because it allows checking whether a function (reader) can be
+applied to a value and apply it to this value at the same time. Now `Reader` trait has this method
+and it is defined and used correctly by the built-in `Reader` combinators, in particular,
+for error checks.
 
-* Added proper error handling.
+### Added proper error handling.
 
-  While writing data to backend representation is usually an error-free operation (if there is a writer
-  for some type, it should handle all values of this type), reading data from the backend representation
-  is a source of errors. This happens because the backend representation has much weaker typing guarantees
-  than Scala code and can't correspond directly to Scala types.
-
-  Previously picopickle didn't provide any special error handling. If the backend value couldn't be
-  deserialized, picopickle would throw some obscure `MatchError` or `IllegalArgumentException`. Since
-  0.2.0 picopickle has a proper exception system, and if a read error occurs, the exception would contain
-  much more information about what was expected and what was actually found. You can find more on it
-  in [Readme][readme-error-handling].
-
-* Added new BSON-based backend.
+While writing data to backend representation is usually an error-free operation (if there is a writer
+for some type, it should handle all values of this type), reading data from the backend representation
+is a source of errors. This happens because the backend representation has much weaker typing guarantees
+than Scala code and can't correspond directly to Scala types.
 
-  A new officially supported backend has been added. It uses [MongoDB BSON][mongodb-bson] data types
-  as the backend representation.
-
-  With this backend it is possible to use picopickle for serialization using the official Mongo drivers.
+Previously picopickle didn't provide any special error handling. If the backend value couldn't be
+deserialized, picopickle would throw some obscure `MatchError` or `IllegalArgumentException`. Since
+0.2.0 picopickle has a proper exception system, and if a read error occurs, the exception would contain
+much more information about what was expected and what was actually found. You can find more on it
+in [Readme][readme-error-handling].
 
-  It also serves as an example extended backend implementation with more types than the basic backend
-  supports.
+### Added new BSON-based backend.
 
-* Added support for changing STH discriminator key on per-STH basis.
+A new officially supported backend has been added. It uses [MongoDB BSON][mongodb-bson] data types
+as the backend representation.
 
-  It is now possible to change sealed trait hierarchy discriminator key for each sealed trait separately:
-
-  ```scala
-  @discriminator("status") sealed trait Root
-  case object Stopped extends Root
-  case class Running(name: String) extends Root
-
-  writeString[Root](Stopped)       shouldEqual """{"status":"Stopped"}"""
-  writeString[Root](Running("me")) shouldEqual """{"status":"Running","name":"me"}"""
-  ```
-
-  This allows even more flexibility in defining serialization formats, especially when matching some
-  existing interface.
+With this backend it is possible to use picopickle for serialization using the official Mongo drivers.
+
+It also serves as an example extended backend implementation with more types than the basic backend
+supports.
+
+### Added support for changing STH discriminator key on per-STH basis.
+
+It is now possible to change sealed trait hierarchy discriminator key for each sealed trait separately:
+
+    @discriminator("status") sealed trait Root
+    case object Stopped extends Root
+    case class Running(name: String) extends Root
+
+    writeString[Root](Stopped)       shouldEqual """{"status":"Stopped"}"""
+    writeString[Root](Running("me")) shouldEqual """{"status":"Running","name":"me"}"""
+
+This allows even more flexibility in defining serialization formats, especially when matching some
+existing interface.
 
 More information can be found in the [readme](https://github.com/netvl/picopickle#readme).