Improve Scaladocs (close #48)

Author: dilyand

iglu-core-circe/src/main/scala/com.snowplowanalytics.iglu.core.circe/CirceIgluCodecs.scala

@@ -19,7 +19,8 @@ import io.circe.syntax._
 import com.snowplowanalytics.iglu.core._
 
 /**
-  * Example of Circe codecs for Iglu entities
+  * Circe codecs for Iglu entities,
+  * such as self-describing schema and self-describing data.
   */
 trait CirceIgluCodecs {
 

iglu-core-json4s/src/main/scala/com.snowplowanalytics.iglu.core.json4s/Json4sIgluCodecs.scala

@@ -17,18 +17,19 @@ import org.json4s._
 import org.json4s.JsonDSL._
 
 /**
-  * Example of serializers for JSON Schema
+  * Json4s serializers for Iglu entities,
+  * such as self-describing schema and self-describing data.
   */
 object Json4sIgluCodecs {
 
-  // Public formats. Import it
+  // Public formats. Import it.
   lazy val formats: Formats = schemaFormats + SchemaSerializer + DataSerializer
 
   // Local formats
   implicit private val schemaFormats: Formats = DefaultFormats + SchemaVerSerializer
 
   /**
-    * Extract SchemaVer (*-*-*) from JValue
+    * Extract `SchemaVer` (*-*-*) from `JValue`.
     */
   object SchemaVerSerializer
       extends CustomSerializer[SchemaVer.Full](
@@ -48,7 +49,8 @@ object Json4sIgluCodecs {
       )
 
   /**
-    * Extract `SchemaKey` from `self` key and remaining as Schema body
+    * Extract `SchemaKey` from the "self" property of a
+    * self-describing schema, and the remaining properties as schema body.
     */
   object SchemaSerializer
       extends CustomSerializer[SelfDescribingSchema[JValue]](
@@ -71,7 +73,8 @@ object Json4sIgluCodecs {
       )
 
   /**
-    * Extract `SchemaKey` from string and data from data key
+    * Extract `SchemaKey` from the "schema" property,
+    * and data from the "data" property.
     */
   object DataSerializer
       extends CustomSerializer[SelfDescribingData[JValue]](

src/main/scala/com.snowplowanalytics.iglu/core/ParseError.scala

@@ -12,7 +12,9 @@
  */
 package com.snowplowanalytics.iglu.core
 
-/** Common error type for parsing core Iglu entities */
+/** A common error type for failures when parsing core Iglu entities,
+  * such as self-describing schema and self-describing data.
+  */
 sealed trait ParseError extends Product with Serializable {
   def code: String
   def message(str: String): String
@@ -98,12 +100,12 @@ object ParseError {
   /**
     * The metaschema URI appears to be invalid.
     *
-    * A valid Iglu schema must make use of the "$schema" keyword
+    * A valid Iglu schema must make use of the \$schema keyword
     * to declare that it conforms to the 'com.snowplowanalytics.self-desc/schema'
     * metaschema.
     *
     * The valid format is:
-    * {{{"$schema" : "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#"}}}.
+    * {{{"\$schema" : "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#"}}}.
     *
     * It's likely this declaration is missing or malformed.
     */
@@ -117,7 +119,7 @@ object ParseError {
       _.code == string
     }
 
-  /** List parse function to get an entity that failed parsing */
+  /** Add an input that failed parsing to the error. */
   def liftParse[A, B](parser: A => Either[ParseError, B]): A => Either[(ParseError, A), B] =
     a => parser(a).left.map(e => (e, a))
 }

src/main/scala/com.snowplowanalytics.iglu/core/PartialSchemaKey.scala

@@ -15,8 +15,9 @@ package com.snowplowanalytics.iglu.core
 import scala.util.matching.Regex
 
 /**
-  * Entity describing schema of data, which **can** be unknown,
-  * by known or unknown `SchemaVer`. Extracted from `schema` key.
+  * Contains details about the schema of a piece of self-describing data.
+  *
+  * Unlike [[SchemaKey]], the schema version may not be fully known.
   */
 final case class PartialSchemaKey(
   vendor: String,
@@ -25,15 +26,11 @@ final case class PartialSchemaKey(
   version: SchemaVer
 ) {
 
-  /**
-    * Converts the SchemaKey back to an Iglu-format schema URI
-    *
-    * @return the SchemaKey as a Iglu-format schema URI
-    */
+  /** Convert this [[PartialSchemaKey]] to an Iglu schema URI. */
   def toSchemaUri: String =
     s"iglu:$vendor/$name/$format/${version.asString}"
 
-  /** Transform to fully known `SchemaKey` */
+  /** Convert this [[PartialSchemaKey]] to a fully-known [[SchemaKey]]. */
   def toSchemaKey: Option[SchemaKey] =
     version match {
       case full: SchemaVer.Full =>
@@ -42,9 +39,10 @@ final case class PartialSchemaKey(
     }
 }
 
+/** Companion object, which contains a custom constructor for [[PartialSchemaKey]]. */
 object PartialSchemaKey {
 
-  /** Canonical regular expression for SchemaKey */
+  /** Canonical regular expression for a [[PartialSchemaKey]]. */
   val schemaUriRegex: Regex = ("^iglu:" + // Protocol
     "([a-zA-Z0-9-_.]+)/" + // Vendor
     "([a-zA-Z0-9-_]+)/" + // Name
@@ -54,14 +52,15 @@ object PartialSchemaKey {
     "((?:0|[1-9][0-9]*)|\\?)").r // ADDITION
 
   /**
-    * Custom constructor for an Iglu partial SchemaKey from
-    * an Iglu-format schema URI, which looks like:
-    * iglu:com.snowplowanalytics.snowplow/mobile_context/jsonschema/1-0-0 for full or
-    * iglu:com.snowplowanalytics.snowplow/mobile_context/jsonschema/1-?-? for partial
-    * Default for Schema reference
+    * A custom constructor for a [[PartialSchemaKey]] from
+    * an Iglu schema URI, which looks like:
+    * "iglu:com.vendor/schema_name/jsonschema/1-0-0" for a fully known version or
+    * "iglu:com.vendor/schema_name/jsonschema/1-?-?" for a partially known version.
+    *
+    * An Iglu schema URI is the default for schema lookup.
     *
-    * @param schemaUri an Iglu-format Schema URI
-    * @return some (possibly partial) schema key if `schemaUri` was valid
+    * @param schemaUri An Iglu schema URI.
+    * @return A [[PartialSchemaKey]] or an error.
     */
   def fromUri(schemaUri: String): Either[ParseError, PartialSchemaKey] = schemaUri match {
     case schemaUriRegex(vnd, n, f, m, r, a) =>

src/main/scala/com.snowplowanalytics.iglu/core/Resolver.scala

@@ -13,18 +13,21 @@
 package com.snowplowanalytics.iglu.core
 
 /**
-  * Entity allowing to fetch and validate schemas for entities of `A`
-  * Resolvers supposed to be implemented as separate artifacts
+  * A [[Resolver]] allows fetching and validating self-describing schemas
+  * for entities of type `A`.
   *
-  * @tparam F effect, wrapping resolver's work (such as `Either[String, Option[A]]` or `IO[A]`
-  * @tparam A AST for data and schema
+  * Resolvers are meant to be implemented as separate artifacts.
+  *
+  * @tparam F An effect wrapping the [[Resolver]]'s work,
+  *           such as `Either[String, Option[A]]` or `IO[A]`.
+  * @tparam A An AST for data or schema.
   */
 trait Resolver[F[_], A] {
 
-  /** Lookup for a schema by its key */
+  /** Look up a schema by its key. */
   def lookup(data: SchemaKey): F[SelfDescribingSchema[A]]
 
-  /** Validate self-describing data against some schema */
+  /** Validate a piece of self-describing data against a schema. */
   def validate(
     data: SelfDescribingData[A],
     schema: SelfDescribingSchema[A]

src/main/scala/com.snowplowanalytics.iglu/core/SchemaCriterion.scala

@@ -15,9 +15,7 @@ package core
 
 import typeclasses.ExtractSchemaKey
 
-/**
-  * Class to filter Schemas by [[SchemaKey]]
-  */
+/** Filter self-describing schemas by [[SchemaKey]]. */
 final case class SchemaCriterion(
   vendor: String,
   name: String,
@@ -28,33 +26,34 @@ final case class SchemaCriterion(
 ) {
 
   /**
-    * Whether a SchemaKey is valid.
+    * Check if a [[SchemaKey]] is valid.
     *
     * It's valid if the vendor, name, format, and model all match
-    * and the supplied key's revision and addition do not exceed the
-    * criterion's revision and addition.
+    * and the supplied key's REVISION and ADDITION do not exceed the
+    * criterion's REVISION and ADDITION.
     *
-    * @param key The SchemaKey to validate
-    * @return whether the SchemaKey is valid
+    * @param key The [[SchemaKey]] to validate.
+    * @return `true` if the [[SchemaKey]] is valid.
     */
   def matches(key: SchemaKey): Boolean =
     prefixMatches(key) && verMatch(key.version)
 
   /**
-    * Filter sequence of entities by this [[SchemaCriterion]]
-    * It can be applied for getting only right JSON instances
-    * out of array with custom context
+    * Filter a sequence of entities by this [[SchemaCriterion]].
+    *
+    * Can be used for getting only the `Right` JSON instances
+    * out of an array of custom contexts.
     *
     * Usage:
     * {{{
-    *   // This will get best matching entity
+    *   // This will get the best match for an entity
     *   criterion.takeFrom(_.schema)(entities).sort.getOption
     * }}}
     *
-    * @param entities list of Self-describing instances (or Schemas)
-    * @tparam E type of Self-describing entity, having
-    *           an `ExtractSchemaKey` instance in scope
-    * @return list of matching entities
+    * @param entities A list of self-describing data blobs.
+    * @tparam E The base type of the self-describing data, having
+    *           an `ExtractSchemaKey` instance in scope.
+    * @return A list of matching entities.
     */
   def pickFrom[E: ExtractSchemaKey](entities: Seq[E]): Seq[E] =
     entities.foldLeft(Seq.empty[E]) { (acc, cur) =>
@@ -65,46 +64,45 @@ final case class SchemaCriterion(
     }
 
   /**
-    * Format as a schema URI, but the revision and addition
-    * may be replaced with "*" wildcards.
+    * Format this [[SchemaCriterion]] as an Iglu schema URI,
+    * whereby the REVISION and ADDITION may be replaced with
+    * "*" wildcards.
     *
-    * @return the String representation of this criterion
+    * @return The string representation of this criterion.
     */
   def asString: String =
     s"iglu:$vendor/$name/$format/$versionString"
 
-  /**
-    * Stringify version part of criterion
-    */
+  /** Stringify the version of this [[SchemaCriterion]]. */
   def versionString: String =
     "%s-%s-%s".format(model.getOrElse("*"), revision.getOrElse("*"), addition.getOrElse("*"))
 
   /**
-    * Whether the vendor, name, and format are all correct.
+    * Check if the vendor, name, and format are all valid.
     *
-    * @param key The SchemaKey to validate
-    * @return whether the first three fields are correct
+    * @param key The [[SchemaKey]] to validate.
+    * @return `true` if the first three fields are correct.
     */
   private def prefixMatches(key: SchemaKey): Boolean =
     key.vendor == vendor && key.name == name && key.format == format
 
   /**
-    * Match only [[SchemaVer]]
+    * Match only [[SchemaVer]].
     *
-    * @param ver SchemaVer of some other [[SchemaKey]]
-    * @return true if all specified groups matched
+    * @param ver A [[SchemaVer]] of some other [[SchemaKey]].
+    * @return `true` if all specified groups match.
     */
   private[this] def verMatch(ver: SchemaVer): Boolean =
     groupMatch(ver.getModel, model) &&
       groupMatch(ver.getRevision, revision) &&
       groupMatch(ver.getAddition, addition)
 
   /**
-    * Helper function for [[verMatch]]. Compares two numbers for same group
+    * Helper function for `verMatch`. Compares two numbers for the same group.
     *
-    * @param other Schema's SchemaVer group (MODEL, REVISION, ADDITION)
-    * @param crit this Criterion's corresponding group
-    * @return true if groups match or criterion not specific about it
+    * @param other The other schema's [[SchemaVer]] group (MODEL, REVISION, ADDITION).
+    * @param crit This [[SchemaCriterion]]'s corresponding group.
+    * @return `true` if the groups match or if either entities are unknown.
     */
   private[this] def groupMatch(other: Option[Int], crit: Option[Int]): Boolean = crit match {
     case Some(c) if other == Some(c) => true
@@ -114,14 +112,10 @@ final case class SchemaCriterion(
   }
 }
 
-/**
-  * Companion object containing alternative constructor for a [[SchemaCriterion]]
-  */
+/** Companion object, which contains custom constructors for [[SchemaCriterion]]. */
 object SchemaCriterion {
 
-  /**
-    * Canonical regex to extract Schema criterion
-    */
+  /** Canonical regular expression to extract [[SchemaCriterion]]. */
   val criterionRegex = ("^iglu:" + // Protocol
     "([a-zA-Z0-9-_.]+)/" + // Vendor
     "([a-zA-Z0-9-_]+)/" + // Name
@@ -131,11 +125,14 @@ object SchemaCriterion {
     "((?:0|[1-9][0-9]*)|\\*)$").r // ADDITION
 
   /**
-    * Custom constructor for an SchemaCriterion from a string, like
-    * iglu:com.snowplowanalytics.snowplow/mobile_context/jsonschema/1-*-*
+    * A custom constructor for a [[SchemaCriterion]] from
+    * a string like:
+    * "iglu:com.vendor/schema_name/jsonschema/1-*-*".
+    *
+    * An Iglu schema URI is the default for schema lookup.
     *
-    * @param criterion string supposed to be criterion
-    * @return criterion object if string satisfies a format
+    * @param criterion The string to convert to a [[SchemaCriterion]].
+    * @return A [[SchemaCriterion]] if the string satisfies the format.
     */
   def parse(criterion: String): Option[SchemaCriterion] =
     criterion match {
@@ -145,9 +142,9 @@ object SchemaCriterion {
     }
 
   /**
-    * Constructs an exhaustive SchemaCriterion.
+    * Constructs a comprehensive [[SchemaCriterion]].
     *
-    * @return our constructed SchemaCriterion
+    * @return the constructed [[SchemaCriterion]].
     */
   def apply(
     vendor: String,
@@ -160,10 +157,10 @@ object SchemaCriterion {
     SchemaCriterion(vendor, name, format, Some(model), Some(revision), Some(addition))
 
   /**
-    * Constructs a SchemaCriterion from everything
-    * except the addition.
+    * Constructs a [[SchemaCriterion]] with everything
+    * except ADDITION.
     *
-    * @return our constructed SchemaCriterion
+    * @return the constructed [[SchemaCriterion]].
     */
   def apply(
     vendor: String,
@@ -175,18 +172,17 @@ object SchemaCriterion {
     SchemaCriterion(vendor, name, format, Some(model), Some(revision))
 
   /**
-    * Constructs a SchemaCriterion which is agnostic
-    * of addition and revision.
-    * Restricts to model only.
+    * Constructs a [[SchemaCriterion]], which is agnostic
+    * about REVISION and ADDITION (restricted to MODEL only).
     *
-    * @return our constructed SchemaCriterion
+    * @return the constructed [[SchemaCriterion]].
     */
   def apply(vendor: String, name: String, format: String, model: Int): SchemaCriterion =
     SchemaCriterion(vendor, name, format, Some(model), None, None)
 
   /**
-    * Try to parse string number
-    * Helper method for [[parse]]
+    * Try to parse a string as a number.
+    * Helper method for [[parse]].
     */
   private def parseInt(number: String): Option[Int] =
     try {