Improve documentation

pipez/src/main/scala-2/pipez/PipeAutoSupport.scala

@@ -5,6 +5,7 @@ import scala.language.experimental.macros
 /** Mix-in providing `derive` method for automatic `Pipe` derivation allowing recursion but not custom configuration */
 trait PipeAutoSupport[Pipe[_, _]] {
 
+  /** Derives `Pipe[In, Out]` using default settings, defined as implicit */
   implicit def deriveAutomatic[In, Out](implicit
     pipeDerivation: PipeDerivation[Pipe]
   ): Pipe[In, Out] = macro pipez.internal.Macro.deriveDefault[Pipe, In, Out]

pipez/src/main/scala-2/pipez/PipeDerivationPlatform.scala

@@ -2,7 +2,7 @@ package pipez
 
 import scala.language.experimental.macros
 
-trait PipeDerivationPlatform { self: PipeDerivation.type =>
+private[pipez] trait PipeDerivationPlatform { self: PipeDerivation.type =>
 
   def derive[Pipe[_, _], In, Out](implicit
     pipeDerivation: PipeDerivation[Pipe]

pipez/src/main/scala-2/pipez/PipeSemiautoConfiguredSupport.scala

@@ -5,14 +5,20 @@ import scala.language.experimental.macros
 /** Mix-in providing `derive` method for semiautomatic `Pipe` derivation without recursion and custom configuration */
 trait PipeSemiautoConfiguredSupport[Pipe[_, _]] {
 
+  /** Derives `Pipe[In, Out]` using provided settings */
   def derive[In, Out](
     config: PipeDerivationConfig[Pipe, In, Out]
   )(implicit
     pipeDerivation: PipeDerivation[Pipe]
   ): Pipe[In, Out] = macro pipez.internal.Macro.deriveConfigured[Pipe, In, Out]
 
+  /** Utility useful for providing configuration to macro.
+    *
+    * Example: `TypeClass.derive(TypeClass.Config[In, Out].enableDiagnostics)`.
+    */
   object Config {
 
+    /** Initiates the config object. Should be used ONLY within `TypeClass.derive(...)` */
     def apply[In, Out]: PipeDerivationConfig[Pipe, In, Out] = ???
   }
 }

pipez/src/main/scala-2/pipez/PipeSemiautoSupport.scala

@@ -5,6 +5,7 @@ import scala.language.experimental.macros
 /** Mix-in providing `derive` method for semiautomatic `Pipe` derivation without recursion and default config */
 trait PipeSemiautoSupport[Pipe[_, _]] {
 
+  /** Derives `Pipe[In, Out]` using default settings */
   def derive[In, Out](implicit
     pipeDerivation: PipeDerivation[Pipe]
   ): Pipe[In, Out] = macro pipez.internal.Macro.deriveDefault[Pipe, In, Out]

pipez/src/main/scala-3/pipez/PipeAutoSupport.scala

@@ -1,7 +1,9 @@
 package pipez
 
+/** Mix-in providing `derive` method for automatic `Pipe` derivation allowing recursion but not custom configuration */
 trait PipeAutoSupport[Pipe[_, _]] {
 
+  /** Derives `Pipe[In, Out]` using default settings, defined as implicit */
   implicit inline def deriveAutomatic[In, Out](implicit
     pipeDerivation: PipeDerivation[Pipe]
   ): Pipe[In, Out] = ${ pipez.internal.Macros.deriveDefault[Pipe, In, Out]('{ pipeDerivation }) }

pipez/src/main/scala-3/pipez/PipeDerivationPlatform.scala

@@ -1,6 +1,6 @@
 package pipez
 
-trait PipeDerivationPlatform { self: PipeDerivation.type =>
+protected[pipez] trait PipeDerivationPlatform { self: PipeDerivation.type =>
 
   inline def derive[Pipe[_, _], In, Out](using
     pipeDerivation: PipeDerivation[Pipe]

pipez/src/main/scala-3/pipez/PipeSemiautoConfiguredSupport.scala

@@ -1,15 +1,22 @@
 package pipez
 
+/** Mix-in providing `derive` method for semiautomatic `Pipe` derivation without recursion and custom configuration */
 trait PipeSemiautoConfiguredSupport[Pipe[_, _]] {
 
+  /** Derives `Pipe[In, Out]` using provided settings */
   inline def derive[Pipe[_, _], In, Out](
     inline config: PipeDerivationConfig[Pipe, In, Out]
   )(using
     pipeDerivation: PipeDerivation[Pipe]
   ): Pipe[In, Out] = ${ pipez.internal.Macros.deriveConfigured[Pipe, In, Out]('{ config })('{ pipeDerivation }) }
 
+  /** Utility useful for providing configuration to macro.
+    *
+    * Example: `TypeClass.derive(TypeClass.Config[In, Out].enableDiagnostics)`.
+    */
   object Config {
 
+    /** Initiates the config object. Should be used ONLY within `TypeClass.derive(...)` */
     def apply[In, Out]: PipeDerivationConfig[Pipe, In, Out] = ???
   }
 }

pipez/src/main/scala-3/pipez/PipeSemiautoSupport.scala

@@ -2,6 +2,7 @@ package pipez
 
 trait PipeSemiautoSupport[Pipe[_, _]] {
 
+  /** Derives `Pipe[In, Out]` using default settings */
   inline def derive[In, Out](using
     inline pipeDerivation: PipeDerivation[Pipe]
   ): Pipe[In, Out] = ${ pipez.internal.Macros.deriveDefault[Pipe, In, Out]('{ pipeDerivation }) }

pipez/src/main/scala/pipez/Path.scala

@@ -1,11 +1,16 @@
 package pipez
 
-sealed abstract class Path(show: String) extends Product with Serializable {
+/** Represents path to the value from the object that was passed into `Pipe` to the parsed field.
+  *
+  * You can use it in `pipeDerivation.updateContext(context, path)` definition, so that before parsing of value
+  * `Context` would be enriched with an information how this value was obtained.
+  *
+  * It allows generating error messages with information where parsing failed.
+  */
+sealed abstract class Path(override val toString: String) extends Product with Serializable {
 
   final def field(name: String):   Path = Path.Field(this, name)
   final def subtype(name: String): Path = Path.Subtype(this, name)
-
-  override lazy val toString = show
 }
 object Path {