added some docs to TypedMap

Author: Roman Janusz

commons-core/src/main/scala/com/avsystem/commons/misc/TypedMap.scala

@@ -1,16 +1,59 @@
-package com.avsystem.commons
-package misc
+package com.avsystem.commons.misc
 
+import com.avsystem.commons.SharedExtensions._
 import com.avsystem.commons.misc.TypedMap.GenCodecMapping
 import com.avsystem.commons.serialization._
 
+/**
+  * A map whose keys are parameterized with value type.
+  * This makes it possible to associate different value type with each key, in a type-safe way.
+  *
+  * [[TypedMap[K]]] has a [[GenCodec]] instance as long as there is a `GenCodec[K[_]]` instance for the key
+  * type and a [[GenCodecMapping[K]]] instance that determines the codec for the value type associated with given
+  * key.
+  *
+  * Example:
+  * {{{
+  *   sealed abstract class AttributeKey[T](implicit val valueCodec: GenCodec[T])
+  *     extends TypedKey[T] with AutoNamedEnum
+  *
+  *   object AttributeKey extends NamedEnumCompanion[AttributeKey[_]] {
+  *     object StringKey extends AttributeKey[String]
+  *     object IntKey extends AttributeKey[Int]
+  *
+  *     val values: List[AttributeKey[_]] = caseObjects
+  *   }
+  *
+  *   val attributes = TypedMap[AttributeKey](
+  *     AttributeKey.StringKey -> "foo",
+  *     AttributeKey.IntKey -> 42,
+  *   )
+  * }}}
+  *
+  * Note that since all keys and value types are known statically,
+  * the map above is somewhat equivalent to a case class:
+  *
+  * {{{
+  *   case class Attributes(
+  *     string: Opt[String],
+  *     int: Opt[Int]
+  *   )
+  * }}}
+  *
+  * [[TypedMap]] might be a good choice if there is a lot of attribute keys, they aren't statically known or some
+  * collection-like behaviour is necessary (e.g. computing the size, iterating over all elements). A [[TypedMap]]
+  * is also easier to evolve than a case class (e.g. because of binary compatibility issues).
+  */
 class TypedMap[K[_]](val raw: Map[K[_], Any]) extends AnyVal {
   def apply[T](key: K[T]): T =
     raw(key).asInstanceOf[T]
 
   def get[T](key: K[T]): Option[T] =
     raw.get(key).asInstanceOf[Option[T]]
 
+  def getOpt[T](key: K[T]): Opt[T] =
+    raw.getOpt(key).asInstanceOf[Opt[T]]
+
   def getOrElse[T](key: K[T], defaultValue: => T): T =
     get(key).getOrElse(defaultValue)