Merge pull request #665 from square/egorand/191007/dokka-0.10.0

Dokka 0.10.0

Author: Egor Andreevich

build.gradle

@@ -3,7 +3,7 @@ buildscript {
       'kotlin': '1.3.50',
       'jmhPlugin': '0.4.8',
       'animalSnifferPlugin': '1.5.0',
-      'dokka': '0.9.18',
+      'dokka': '0.10.0',
       'jmh': '1.21',
       'animalSniffer': '1.16',
       'junit': '4.12',

gradle/gradle-mvn-mpp-push.gradle

@@ -5,47 +5,38 @@ apply plugin: 'org.jetbrains.dokka'
 dokka {
   outputDirectory = "$rootDir/docs/2.x"
   outputFormat = 'gfm'
-  reportUndocumented = false
-  skipDeprecated = true
-  jdkVersion = 8
-  impliedPlatforms = ["Common"] // This will force platform tags for all non-common sources e.g. "JVM"
-  kotlinTasks {
-    // dokka fails to retrieve sources from MPP-tasks so they must be set empty to avoid exception
-    // use sourceRoot instead (see below)
-    []
-  }
-  packageOptions {
-    prefix = "com.squareup.okio"
-    suppress = true
-  }
-  packageOptions {
-    prefix = "okio.internal"
-    suppress = true
-  }
-  sourceRoot {
-    // assuming there is only a single source dir...
-    path = kotlin.sourceSets.commonMain.kotlin.srcDirs[0]
-    platforms = ["Common"]
-  }
-  if (kotlin.sourceSets.getNames().contains("jvmMain")) {
-    sourceRoot {
-      // assuming there is only a single source dir...
-      path = kotlin.sourceSets.jvmMain.kotlin.srcDirs[0]
-      platforms = ["JVM"]
+
+  multiplatform {
+    global {
+      reportUndocumented = false
+      skipDeprecated = true
+      jdkVersion = 8
+      perPackageOption {
+        prefix = "com.squareup.okio"
+        suppress = true
+      }
+      perPackageOption {
+        prefix = "okio.internal"
+        suppress = true
+      }
     }
-  }
-  if (kotlin.sourceSets.getNames().contains("jsMain")) {
-    sourceRoot {
-      // assuming there is only a single source dir...
-      path = kotlin.sourceSets.jsMain.kotlin.srcDirs[0]
-      platforms = ["js"]
+    jvm {
+      sourceRoot {
+        // assuming there is only a single source dir...
+        path = kotlin.sourceSets.jvmMain.kotlin.srcDirs[0]
+      }
     }
-  }
-  if (kotlin.sourceSets.getNames().contains("nativeMain")) {
-    sourceRoot {
-      // assuming there is only a single source dir...
-      path = kotlin.sourceSets.nativeMain.kotlin.srcDirs[0]
-      platforms = ["native"]
+    js {
+      sourceRoot {
+        // assuming there is only a single source dir...
+        path = kotlin.sourceSets.jsMain.kotlin.srcDirs[0]
+      }
+    }
+    'native' {
+      sourceRoot {
+        // assuming there is only a single source dir...
+        path = kotlin.sourceSets.nativeMain.kotlin.srcDirs[0]
+      }
     }
   }
 }

okio/src/commonMain/kotlin/okio/Buffer.kt

@@ -65,8 +65,13 @@ expect class Buffer() : BufferedSource, BufferedSink {
   /** Returns the byte at `pos`. */
   operator fun get(pos: Long): Byte
 
+  /**
+   * Discards all bytes in this buffer. Calling this method when you're done with a buffer will
+   * return its segments to the pool.
+   */
   fun clear()
 
+  /** Discards `byteCount` bytes from the head of this buffer.  */
   override fun skip(byteCount: Long)
 
   override fun write(byteString: ByteString): Buffer

okio/src/jsMain/kotlin/okio/Buffer.kt

@@ -83,21 +83,13 @@ actual class Buffer : BufferedSource, BufferedSink {
     byteCount: Long
   ): Buffer = commonCopyTo(out, offset, byteCount)
 
-  /**
-   * Overload of [copyTo] with byteCount = size - offset, work around for
-   *  https://youtrack.jetbrains.com/issue/KT-30847
-   */
   actual fun copyTo(
     out: Buffer,
     offset: Long
   ): Buffer = copyTo(out, offset, size - offset)
 
   actual operator fun get(pos: Long): Byte = commonGet(pos)
 
-  /**
-   * Returns the number of bytes in segments that are not writable. This is the number of bytes that
-   * can be flushed immediately to an underlying sink without harming throughput.
-   */
   actual fun completeSegmentByteCount(): Long = commonCompleteSegmentByteCount()
 
   override fun readByte(): Byte = commonReadByte()
@@ -248,12 +240,9 @@ actual class Buffer : BufferedSource, BufferedSink {
    */
   override fun toString() = snapshot().toString()
 
-  /** Returns a deep copy of this buffer. */
   actual fun copy(): Buffer = commonCopy()
 
-  /** Returns an immutable copy of this buffer as a byte string.  */
   actual fun snapshot(): ByteString = commonSnapshot()
 
-  /** Returns an immutable copy of the first `byteCount` bytes of this buffer as a byte string. */
   actual fun snapshot(byteCount: Int): ByteString = commonSnapshot(byteCount)
 }

okio/src/jsMain/kotlin/okio/ByteString.kt

@@ -42,93 +42,54 @@ import okio.internal.commonToString
 import okio.internal.commonUtf8
 import okio.internal.commonWrite
 
-/**
- * An immutable sequence of bytes.
- *
- * Byte strings compare lexicographically as a sequence of **unsigned** bytes. That is, the byte
- * string `ff` sorts after `00`. This is counter to the sort order of the corresponding bytes,
- * where `-1` sorts before `0`.
- */
 actual open class ByteString
-// Trusted internal constructor doesn't clone data.
 internal actual constructor(
   internal actual val data: ByteArray
 ) : Comparable<ByteString> {
   internal actual var hashCode: Int = 0 // Lazily computed; 0 if unknown.
   internal actual var utf8: String? = null // Lazily computed.
 
-  /** Constructs a new `String` by decoding the bytes as `UTF-8`.  */
   actual open fun utf8(): String = commonUtf8()
 
-  /**
-   * Returns this byte string encoded as [Base64](http://www.ietf.org/rfc/rfc2045.txt). In violation
-   * of the RFC, the returned string does not wrap lines at 76 columns.
-   */
   actual open fun base64(): String = commonBase64()
 
-  /** Returns this byte string encoded as [URL-safe Base64](http://www.ietf.org/rfc/rfc4648.txt). */
   actual open fun base64Url(): String = commonBase64Url()
 
-  /** Returns this byte string encoded in hexadecimal.  */
   actual open fun hex(): String = commonHex()
 
-  /**
-   * Returns a byte string equal to this byte string, but with the bytes 'A' through 'Z' replaced
-   * with the corresponding byte in 'a' through 'z'. Returns this byte string if it contains no
-   * bytes in 'A' through 'Z'.
-   */
   actual open fun toAsciiLowercase(): ByteString = commonToAsciiLowercase()
 
-  /**
-   * Returns a byte string equal to this byte string, but with the bytes 'a' through 'z' replaced
-   * with the corresponding byte in 'A' through 'Z'. Returns this byte string if it contains no
-   * bytes in 'a' through 'z'.
-   */
   actual open fun toAsciiUppercase(): ByteString = commonToAsciiUppercase()
 
   actual open fun substring(beginIndex: Int, endIndex: Int): ByteString =
       commonSubstring(beginIndex, endIndex)
 
-  /** Returns the byte at `pos`.  */
   internal actual open fun internalGet(pos: Int): Byte {
     if (pos >= size || pos < 0) throw ArrayIndexOutOfBoundsException("size=$size pos=$pos")
     return commonGetByte(pos)
   }
 
-  /** Returns the byte at `index`.  */
   actual operator fun get(index: Int): Byte = internalGet(index)
 
-  /** Returns the number of bytes in this ByteString. */
   actual val size
     get() = getSize()
 
-  // Hack to work around Kotlin's limitation for using JvmName on open/override vals/funs
   internal actual open fun getSize() = commonGetSize()
 
-  /** Returns a byte array containing a copy of the bytes in this `ByteString`. */
   actual open fun toByteArray() = commonToByteArray()
 
-  /** Returns the bytes of this string without a defensive copy. Do not mutate!  */
   internal actual open fun internalArray() = commonInternalArray()
 
   internal actual open fun write(buffer: Buffer, offset: Int, byteCount: Int) =
     commonWrite(buffer, offset, byteCount)
 
-  /**
-   * Returns true if the bytes of this in `[offset..offset+byteCount)` equal the bytes of `other` in
-   * `[otherOffset..otherOffset+byteCount)`. Returns false if either range is out of bounds.
-   */
   actual open fun rangeEquals(
     offset: Int,
     other: ByteString,
     otherOffset: Int,
     byteCount: Int
   ): Boolean = commonRangeEquals(offset, other, otherOffset, byteCount)
 
-  /**
-   * Returns true if the bytes of this in `[offset..offset+byteCount)` equal the bytes of `other` in
-   * `[otherOffset..otherOffset+byteCount)`. Returns false if either range is out of bounds.
-   */
   actual open fun rangeEquals(
     offset: Int,
     other: ByteArray,
@@ -165,25 +126,17 @@ internal actual constructor(
   actual override fun toString() = commonToString()
 
   actual companion object {
-    /** A singleton empty `ByteString`.  */
     actual val EMPTY: ByteString = ByteString(byteArrayOf())
 
-    /** Returns a new byte string containing a clone of the bytes of `data`. */
     actual fun of(vararg data: Byte) = commonOf(data)
 
     actual fun ByteArray.toByteString(offset: Int, byteCount: Int): ByteString =
       commonToByteString(offset, byteCount)
 
-    /** Returns a new byte string containing the `UTF-8` bytes of this [String].  */
     actual fun String.encodeUtf8(): ByteString = commonEncodeUtf8()
 
-    /**
-     * Decodes the Base64-encoded bytes and returns their value as a byte string. Returns null if
-     * this is not a Base64-encoded sequence of bytes.
-     */
     actual fun String.decodeBase64(): ByteString? = commonDecodeBase64()
 
-    /** Decodes the hex-encoded bytes and returns their value a byte string.  */
     actual fun String.decodeHex() = commonDecodeHex()
   }
 }

okio/src/jsMain/kotlin/okio/SegmentedByteString.kt

@@ -24,31 +24,6 @@ import okio.internal.commonSubstring
 import okio.internal.commonToByteArray
 import okio.internal.commonWrite
 
-/**
- * An immutable byte string composed of segments of byte arrays. This class exists to implement
- * efficient snapshots of buffers. It is implemented as an array of segments, plus a directory in
- * two halves that describes how the segments compose this byte string.
- *
- * The first half of the directory is the cumulative byte count covered by each segment. The
- * element at `directory[0]` contains the number of bytes held in `segments[0]`; the
- * element at `directory[1]` contains the number of bytes held in `segments[0] +
- * segments[1]`, and so on. The element at `directory[segments.length - 1]` contains the total
- * size of this byte string. The first half of the directory is always monotonically increasing.
- *
- * The second half of the directory is the offset in `segments` of the first content byte.
- * Bytes preceding this offset are unused, as are bytes beyond the segment's effective size.
- *
- * Suppose we have a byte string, `[A, B, C, D, E, F, G, H, I, J, K, L, M]` that is stored
- * across three byte arrays: `[x, x, x, x, A, B, C, D, E, x, x, x]`, `[x, F, G]`, and `[H, I, J, K,
- * L, M, x, x, x, x, x, x]`. The three byte arrays would be stored in `segments` in order. Since the
- * arrays contribute 5, 2, and 6 elements respectively, the directory starts with `[5, 7, 13` to
- * hold the cumulative total at each position. Since the offsets into the arrays are 4, 1, and 0
- * respectively, the directory ends with `4, 1, 0]`. Concatenating these two halves, the complete
- * directory is `[5, 7, 13, 4, 1, 0]`.
- *
- * This structure is chosen so that the segment holding a particular offset can be found by
- * binary search. We use one array rather than two for the directory as a micro-optimization.
- */
 internal actual class SegmentedByteString internal actual constructor(
   internal actual val segments: Array<ByteArray>,
   internal actual val directory: IntArray

okio/src/jvmMain/kotlin/okio/Buffer.kt

@@ -356,13 +356,8 @@ actual class Buffer : BufferedSource, BufferedSink, Cloneable, ByteChannel {
     return toCopy
   }
 
-  /**
-   * Discards all bytes in this buffer. Calling this method when you're done with a buffer will
-   * return its segments to the pool.
-   */
   actual fun clear() = commonClear()
 
-  /** Discards `byteCount` bytes from the head of this buffer.  */
   @Throws(EOFException::class)
   actual override fun skip(byteCount: Long) = commonSkip(byteCount)
 
@@ -556,7 +551,6 @@ actual class Buffer : BufferedSource, BufferedSink, Cloneable, ByteChannel {
    */
   override fun toString() = snapshot().toString()
 
-  /** Returns a deep copy of this buffer. */
   actual fun copy(): Buffer = commonCopy()
 
   /** Returns a deep copy of this buffer. */

okio/src/jvmMain/kotlin/okio/ByteString.kt

@@ -56,7 +56,6 @@ import javax.crypto.Mac
 import javax.crypto.spec.SecretKeySpec
 
 actual open class ByteString
-// Trusted internal constructor doesn't clone data.
 internal actual constructor(
   internal actual val data: ByteArray
 ) : Serializable, Comparable<ByteString> {
@@ -124,7 +123,6 @@ internal actual constructor(
   actual val size
     @JvmName("size") get() = getSize()
 
-  // Hack to work around Kotlin's limitation for using JvmName on open/override vals/funs
   internal actual open fun getSize() = commonGetSize()
 
   actual open fun toByteArray() = commonToByteArray()

okio/src/jvmMain/kotlin/okio/SegmentedByteString.kt

@@ -33,31 +33,6 @@ import java.security.MessageDigest
 import javax.crypto.Mac
 import javax.crypto.spec.SecretKeySpec
 
-/**
- * An immutable byte string composed of segments of byte arrays. This class exists to implement
- * efficient snapshots of buffers. It is implemented as an array of segments, plus a directory in
- * two halves that describes how the segments compose this byte string.
- *
- * The first half of the directory is the cumulative byte count covered by each segment. The
- * element at `directory[0]` contains the number of bytes held in `segments[0]`; the
- * element at `directory[1]` contains the number of bytes held in `segments[0] +
- * segments[1]`, and so on. The element at `directory[segments.length - 1]` contains the total
- * size of this byte string. The first half of the directory is always monotonically increasing.
- *
- * The second half of the directory is the offset in `segments` of the first content byte.
- * Bytes preceding this offset are unused, as are bytes beyond the segment's effective size.
- *
- * Suppose we have a byte string, `[A, B, C, D, E, F, G, H, I, J, K, L, M]` that is stored
- * across three byte arrays: `[x, x, x, x, A, B, C, D, E, x, x, x]`, `[x, F, G]`, and `[H, I, J, K,
- * L, M, x, x, x, x, x, x]`. The three byte arrays would be stored in `segments` in order. Since the
- * arrays contribute 5, 2, and 6 elements respectively, the directory starts with `[5, 7, 13` to
- * hold the cumulative total at each position. Since the offsets into the arrays are 4, 1, and 0
- * respectively, the directory ends with `4, 1, 0]`. Concatenating these two halves, the complete
- * directory is `[5, 7, 13, 4, 1, 0]`.
- *
- * This structure is chosen so that the segment holding a particular offset can be found by
- * binary search. We use one array rather than two for the directory as a micro-optimization.
- */
 internal actual class SegmentedByteString internal actual constructor(
   @Transient internal actual val segments: Array<ByteArray>,
   @Transient internal actual val directory: IntArray

okio/src/nativeMain/kotlin/okio/Buffer.kt

@@ -83,21 +83,13 @@ actual class Buffer : BufferedSource, BufferedSink {
     byteCount: Long
   ): Buffer = commonCopyTo(out, offset, byteCount)
 
-  /**
-   * Overload of [copyTo] with byteCount = size - offset, work around for
-   *  https://youtrack.jetbrains.com/issue/KT-30847
-   */
   actual fun copyTo(
     out: Buffer,
     offset: Long
   ): Buffer = copyTo(out, offset, size - offset)
 
   actual operator fun get(pos: Long): Byte = commonGet(pos)
 
-  /**
-   * Returns the number of bytes in segments that are not writable. This is the number of bytes that
-   * can be flushed immediately to an underlying sink without harming throughput.
-   */
   actual fun completeSegmentByteCount(): Long = commonCompleteSegmentByteCount()
 
   override fun readByte(): Byte = commonReadByte()
@@ -248,12 +240,9 @@ actual class Buffer : BufferedSource, BufferedSink {
    */
   override fun toString() = snapshot().toString()
 
-  /** Returns a deep copy of this buffer. */
   actual fun copy(): Buffer = commonCopy()
 
-  /** Returns an immutable copy of this buffer as a byte string.  */
   actual fun snapshot(): ByteString = commonSnapshot()
 
-  /** Returns an immutable copy of the first `byteCount` bytes of this buffer as a byte string. */
   actual fun snapshot(byteCount: Int): ByteString = commonSnapshot(byteCount)
 }