Document DataTypes

Author: Mingun

shared/src/main/scala/io/kaitai/struct/datatype/DataType.scala

@@ -31,26 +31,69 @@ object DataType {
     def apiCall(defEndian: Option[FixedEndian]): String
   }
 
+  /** A generic number type. */
   abstract sealed class NumericType extends DataType
+  /** A generic boolean type. */
   abstract sealed class BooleanType extends DataType
 
+  /** A generic integer type. */
   abstract sealed class IntType extends NumericType
+  /** An integer type that occupies undecided number of bytes in the stream. */
   case object CalcIntType extends IntType
+  /**
+    * An integer type that fit into the byte and therefore can represent element of byte array.
+    *
+    * Parameters have this type when it's declared with `type: u1` or `type: s1`.
+    *
+    * @param signed Determines if most significant bit of number contains sign
+    */
   case class Int1Type(signed: Boolean) extends IntType with ReadableType {
     override def apiCall(defEndian: Option[FixedEndian]): String = if (signed) "s1" else "u1"
   }
+  /**
+    * An integer type that occupies some predefined size in bytes in the stream.
+    *
+    * Parameters have this type when it's declared with `type: u<X>` or `type: s<X>`.
+    *
+    * @param signed Determines if most significant bit of number contains sign
+    * @param width Size of type in bytes
+    * @param endian Byte order used to represent the number
+    */
   case class IntMultiType(signed: Boolean, width: IntWidth, endian: Option[FixedEndian]) extends IntType with ReadableType {
     override def apiCall(defEndian: Option[FixedEndian]): String = {
       val ch1 = if (signed) 's' else 'u'
       val finalEnd = endian.orElse(defEndian)
       s"$ch1${width.width}${finalEnd.map(_.toSuffix).getOrElse("")}"
     }
   }
+  /**
+    * A boolean type that occupies one bit in the stream.
+    *
+    * Parameters have this type when it's declared with `type: b1`.
+    */
   case class BitsType1(bitEndian: BitEndianness) extends BooleanType
+  /**
+    * An integer number type that occupies some predefined size in _bits_ in the stream.
+    *
+    * Parameters have this type when it's declared with `type: b<X>`.
+    *
+    * @param width Size of type in bits
+    * @param bitEndian Bit order inside of byte used to represent the number
+    */
   case class BitsType(width: Int, bitEndian: BitEndianness) extends IntType
 
+  /** A generic floating-point number type. */
   abstract sealed class FloatType extends NumericType
+  /** A floating-point number type that occupies undecided number of bytes in the stream. */
   case object CalcFloatType extends FloatType
+  /**
+    * A floating-point number type that occupies some predefined size in bytes in the stream.
+    *
+    * Parameters have this type when it's declared with `type: f<X>`.
+    *
+    * @param width Size of type in bytes
+    * @param endian Byte order used to represent the number
+    */
   case class FloatMultiType(width: IntWidth, endian: Option[FixedEndian]) extends FloatType with ReadableType {
     override def apiCall(defEndian: Option[FixedEndian]): String = {
       val finalEnd = endian.orElse(defEndian)
@@ -62,7 +105,13 @@ object DataType {
     def process: Option[ProcessExpr]
   }
 
+  /** A generic raw bytes type. */
   abstract sealed class BytesType extends DataType with Processing
+  /**
+    * A raw bytes type that occupies undecided number of bytes in the stream.
+    *
+    * Parameters have this type when it's declared with `type: bytes`.
+    */
   case object BorrowedBytesType extends BytesType {
     override def process = None
   }
@@ -87,10 +136,27 @@ object DataType {
     override val process: Option[ProcessExpr]
   ) extends BytesType
 
+  /** A generic string type. */
   abstract sealed class StrType extends DataType
+  /**
+    * A pure string type that occupies undecided number of bytes in the stream.
+    *
+    * Parameters have this type when it's declared with `type: str`.
+    */
   case object CalcStrType extends StrType
+  /**
+    * A type that have the `str` and `strz` built-in Kaitai types.
+    *
+    * @param bytes An underlying bytes of the string
+    * @param encoding An encoding used to convert byte array into string
+    */
   case class StrFromBytesType(bytes: BytesType, encoding: String) extends StrType
 
+  /**
+    * A boolean type that occupies undecided number of bytes in the stream.
+    *
+    * Parameters have this type when it's declared with `type: bool`.
+    */
   case object CalcBooleanType extends BooleanType
 
   /**
@@ -132,6 +198,7 @@ object DataType {
       cs.isTopLevel || cs.meta.isOpaque
     }
   }
+  /** User type which isn't restricted in size (i.e. without `size`, `terminator`, or `size-eos`). */
   case class OwnedUserType(
     _name: List[String],
     _forcedParent: Option[Ast.expr],
@@ -144,6 +211,7 @@ object DataType {
       r
     }
   }
+  /** User type which is restricted in size either via `size`, `terminator`, or `size-eos`. */
   case class OwnedUserTypeFromBytes(
     _name: List[String],
     _forcedParent: Option[Ast.expr],
@@ -175,30 +243,75 @@ object DataType {
     override def isOwning = false
   }
 
+  /**
+    * A generic collection type.
+    *
+    * @param elType Type of elements in the collection
+    */
   abstract sealed class ArrayType(val elType: DataType) extends ComplexDataType
-
+  /**
+    * An owned slice of array type. This type is used for holding data in attributes
+    * with `repeat` key. Number of elements in that type is unknown
+    *
+    * @param _elType Type of elements in the slice
+    */
   case class OwnedSliceType(_elType: DataType) extends ArrayType(_elType) {
     override def isOwning: Boolean = true
     override def asNonOwning: BorrowedSliceType = BorrowedSliceType(elType)
   }
+  /**
+    * A borrowed slice of an array. This type is used when array is passed as a
+    * parameter to the user type (parameter have type `bytes` or haven't any
+    * explicitly defined type). Number of elements in that type is unknown
+    *
+    * @param _elType Type of elements in the slice
+    */
   case class BorrowedSliceType(_elType: DataType) extends ArrayType(_elType) {
     override def isOwning: Boolean = false
   }
 
   val USER_TYPE_NO_PARENT = Ast.expr.Bool(false)
 
+  /**
+    * A very generic type that can hold any other type. Used when type of expression
+    * is completely unknown to the compiler.
+    *
+    * Parameters have this type when it's declared with `type: any`.
+    */
   case object AnyType extends DataType
+
+  /**
+    * A type that can hold any Kaitai generated type. Can be used as common ancestor
+    * of `switch-on` types, when all alternative types is owned.
+    */
   case object OwnedKaitaiStructType extends StructType {
     def isOwning = true
     override def asNonOwning: DataType = BorrowedKaitaiStructType
   }
+  /**
+    * A type that can hold any Kaitai generated type. Can be used as common ancestor
+    * of `switch-on` types, when at least one of the alternative types is borrowed.
+    *
+    * Parameters have this type when it's declared with `type: struct`.
+    */
   case object BorrowedKaitaiStructType extends StructType {
     def isOwning = false
   }
+  /**
+    * A type that hold and own Kaitai stream object. This type is used when a new IO object
+    * is allocated (i.e. when new sub-stream is created for types with `size`, `terminator`,
+    * or `size-eos: true` attributes).
+    */
   case object OwnedKaitaiStreamType extends ComplexDataType {
     def isOwning = true
     override def asNonOwning: DataType = BorrowedKaitaiStreamType
   }
+  /**
+    * A type that hold and borrow Kaitai stream object. This type is used
+    * when an IO object is passed as parameter to the user type.
+    *
+    * Parameters have this type when it's declared with `type: io`.
+    */
   case object BorrowedKaitaiStreamType extends ComplexDataType {
     def isOwning = false
   }
@@ -381,6 +494,8 @@ object DataType {
             case _ => (dt, List())
           }
           val dtl = classNameToList(arglessType)
+          // if `size`, `terminator` and `size-eos: true` isn't defined,
+          // user type uses parent stream, otherwise creates own stream
           if (arg.size.isEmpty && !arg.sizeEos && arg.terminator.isEmpty) {
             if (arg.process.isDefined)
               throw new YAMLParseException(s"user type '$dt': need 'size' / 'size-eos' / 'terminator' if 'process' is used", path)