Merge pull request #1200 from Kotlin/unify-numbers-docs

Number unification docs

Author: Jolanrensen

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/UnifyingNumbers.kt

@@ -27,7 +27,7 @@ import org.jetbrains.kotlinx.dataframe.impl.UnifiedNumberTypeOptions
  *    UByte     Byte
  *        \     /
  *        \    /
- *       Nothing?
+ *       Nothing
  * ```
  * For each number type in the graph, it holds that a number of that type can be expressed lossless by
  * a number of a more complex type (any of its parents).
@@ -40,6 +40,11 @@ import org.jetbrains.kotlinx.dataframe.impl.UnifiedNumberTypeOptions
  *
  * See [UnifiedNumberTypeOptions] for these settings.
  *
- * At the bottom of the graph is [Nothing]. This can be interpreted as `null`.
+ * Nullability, while not displayed in the graph, is also taken into account.
+ * This means that `Int?` and `Float` will be unified to `Double?`.
+ *
+ * At the bottom of the graph is [Nothing].
+ * This can be interpreted as "no type" and can have no instance,
+ * while [Nothing?][Nothing] can only be `null`.
  */
 public interface UnifyingNumbers

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/utils.kt

@@ -50,6 +50,8 @@ internal annotation class ExcludeFromSources
  * @param stripReferences Whether to strip `[references]` from the HTML file. Default is `true`.
  *  This is useful when you want to include the HTML file in a website, where the references are not
  *  needed or would break.
+ * @param includeResizeScript Whether to include a script that helps height recalculation inside iFrames.
+ *  This is useful inside WriterSide. Default is `true`.
  */
 @Target(
     CLASS,
@@ -66,4 +68,8 @@ internal annotation class ExcludeFromSources
     TYPEALIAS,
     FILE,
 )
-internal annotation class ExportAsHtml(val theme: Boolean = true, val stripReferences: Boolean = true)
+internal annotation class ExportAsHtml(
+    val theme: Boolean = true,
+    val stripReferences: Boolean = true,
+    val includeResizeScript: Boolean = true,
+)

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/NumberTypeUtils.kt

@@ -52,7 +52,7 @@ private val unifiedNumberTypeGraphs = mutableMapOf<UnifiedNumberTypeOptions, Dir
  *    UByte     Byte
  *        \     /
  *        \    /
- *       Nothing?
+ *       Nothing
  * ```
  *
  * For any two numbers, we can find the nearest common ancestor in this graph
@@ -127,7 +127,7 @@ internal fun getUnifiedNumberTypeGraph(
  *    UByte     Byte
  *        \     /
  *        \    /
- *       Nothing?
+ *       Nothing
  * ```
  *
  * For any two numbers, we can find the nearest common ancestor in this graph

core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/types/UtilTests.kt

@@ -438,7 +438,7 @@ class UtilTests {
      *    UByte     Byte
      *        \     /
      *        \    /
-     *       Nothing?
+     *       Nothing
      * ```
      */
     @Test

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/UnifyingNumbers.kt

@@ -22,7 +22,12 @@ import org.jetbrains.kotlinx.dataframe.impl.UnifiedNumberTypeOptions
  *
  * See [UnifiedNumberTypeOptions] for these settings.
  *
- * At the bottom of the graph is [Nothing]. This can be interpreted as `null`.
+ * Nullability, while not displayed in the graph, is also taken into account.
+ * This means that `Int?` and `Float` will be unified to `Double?`.
+ *
+ * At the bottom of the graph is [Nothing].
+ * This can be interpreted as "no type" and can have no instance,
+ * while [Nothing?][Nothing] can only be `null`.
  */
 public interface UnifyingNumbers {
 
@@ -44,9 +49,10 @@ public interface UnifyingNumbers {
      *    UByte     Byte
      *        \\     /
      *        \\    /
-     *       Nothing?
+     *       Nothing
      * ```
      */
     @ExcludeFromSources
+    @ExportAsHtml
     private interface Graph
 }

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/utils.kt

@@ -82,6 +82,8 @@ internal annotation class ExcludeFromSources
  * @param stripReferences Whether to strip `[references]` from the HTML file. Default is `true`.
  *  This is useful when you want to include the HTML file in a website, where the references are not
  *  needed or would break.
+ * @param includeResizeScript Whether to include a script that helps height recalculation inside iFrames.
+ *  This is useful inside WriterSide. Default is `true`.
  */
 @Target(
     CLASS,
@@ -98,4 +100,8 @@ internal annotation class ExcludeFromSources
     TYPEALIAS,
     FILE,
 )
-internal annotation class ExportAsHtml(val theme: Boolean = true, val stripReferences: Boolean = true)
+internal annotation class ExportAsHtml(
+    val theme: Boolean = true,
+    val stripReferences: Boolean = true,
+    val includeResizeScript: Boolean = true,
+)

dataframe-csv/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DelimParams.kt

@@ -92,7 +92,7 @@ internal object DelimParams {
      *
      *   Fixed-width columns can occur, for instance, in multi-space delimited data, where the columns are separated
      *   by multiple spaces instead of a single delimiter, so columns are visually aligned.
-     *   Columns widths are determined by the header in the data (if present), or manually by setting
+     *   Column widths are determined by the header in the data (if present), or manually by setting
      *   [fixedColumnWidths].
      */
     const val HAS_FIXED_WIDTH_COLUMNS: Boolean = false
@@ -163,7 +163,7 @@ internal object DelimParams {
     const val IGNORE_EMPTY_LINES: Boolean = false
 
     /**
-     * @param allowMissingColumns Wether to allow rows with fewer columns than the header. Default: `true`.
+     * @param allowMissingColumns Whether to allow rows with fewer columns than the header. Default: `true`.
      *
      *   If `true`, rows that are too short will be interpreted as _empty_ values.
      */
@@ -201,7 +201,7 @@ internal object DelimParams {
      * @param parseParallel Whether to parse the data in parallel. Default: `true`.
      *
      *   If `true`, the data will be read and parsed in parallel by the Deephaven parser.
-     *   This is usually faster, but can be turned off for debugging.
+     *   This is usually faster but can be turned off for debugging.
      */
     const val PARSE_PARALLEL: Boolean = true
 

dataframe-csv/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/io/readDelim.kt

@@ -79,7 +79,7 @@ import kotlin.time.Duration
  *
  *   Fixed-width columns can occur, for instance, in multi-space delimited data, where the columns are separated
  *   by multiple spaces instead of a single delimiter, so columns are visually aligned.
- *   Columns widths are determined by the header in the data (if present), or manually by setting
+ *   Column widths are determined by the header in the data (if present), or manually by setting
  *   [fixedColumnWidths].
  * @param fixedColumnWidths The fixed column widths. Default: empty list.
  *
@@ -102,7 +102,7 @@ import kotlin.time.Duration
  * @param ignoreEmptyLines Whether to skip intermediate empty lines. Default: `false`.
  *
  *   If `false`, empty lines will be interpreted as having _empty_ values if [allowMissingColumns].
- * @param allowMissingColumns Wether to allow rows with fewer columns than the header. Default: `true`.
+ * @param allowMissingColumns Whether to allow rows with fewer columns than the header. Default: `true`.
  *
  *   If `true`, rows that are too short will be interpreted as _empty_ values.
  * @param ignoreExcessColumns Whether to ignore rows with more columns than the header. Default: `true`.
@@ -120,7 +120,7 @@ import kotlin.time.Duration
  * @param parseParallel Whether to parse the data in parallel. Default: `true`.
  *
  *   If `true`, the data will be read and parsed in parallel by the Deephaven parser.
- *   This is usually faster, but can be turned off for debugging.
+ *   This is usually faster but can be turned off for debugging.
  * @param compression The compression of the data.
  *   Default: [Compression.None], unless detected otherwise from the input file or url.
  * @param adjustCsvSpecs Optional extra [CsvSpecs] configuration. Default: `{ it }`.

dataframe-csv/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readCsv.kt

@@ -82,7 +82,7 @@ import kotlin.io.path.inputStream
  *
  *   Fixed-width columns can occur, for instance, in multi-space delimited data, where the columns are separated
  *   by multiple spaces instead of a single delimiter, so columns are visually aligned.
- *   Columns widths are determined by the header in the data (if present), or manually by setting
+ *   Column widths are determined by the header in the data (if present), or manually by setting
  *   [fixedColumnWidths].
  * @param fixedColumnWidths The fixed column widths. Default: empty list.
  *
@@ -119,7 +119,7 @@ import kotlin.io.path.inputStream
  * @param ignoreEmptyLines Whether to skip intermediate empty lines. Default: `false`.
  *
  *   If `false`, empty lines will be interpreted as having _empty_ values if [allowMissingColumns].
- * @param allowMissingColumns Wether to allow rows with fewer columns than the header. Default: `true`.
+ * @param allowMissingColumns Whether to allow rows with fewer columns than the header. Default: `true`.
  *
  *   If `true`, rows that are too short will be interpreted as _empty_ values.
  * @param ignoreExcessColumns Whether to ignore rows with more columns than the header. Default: `true`.
@@ -137,7 +137,7 @@ import kotlin.io.path.inputStream
  * @param parseParallel Whether to parse the data in parallel. Default: `true`.
  *
  *   If `true`, the data will be read and parsed in parallel by the Deephaven parser.
- *   This is usually faster, but can be turned off for debugging.
+ *   This is usually faster but can be turned off for debugging.
  */
 public fun DataFrame.Companion.readCsv(
     path: Path,
@@ -234,7 +234,7 @@ public fun DataFrame.Companion.readCsv(
  *
  *   Fixed-width columns can occur, for instance, in multi-space delimited data, where the columns are separated
  *   by multiple spaces instead of a single delimiter, so columns are visually aligned.
- *   Columns widths are determined by the header in the data (if present), or manually by setting
+ *   Column widths are determined by the header in the data (if present), or manually by setting
  *   [fixedColumnWidths].
  * @param fixedColumnWidths The fixed column widths. Default: empty list.
  *
@@ -271,7 +271,7 @@ public fun DataFrame.Companion.readCsv(
  * @param ignoreEmptyLines Whether to skip intermediate empty lines. Default: `false`.
  *
  *   If `false`, empty lines will be interpreted as having _empty_ values if [allowMissingColumns].
- * @param allowMissingColumns Wether to allow rows with fewer columns than the header. Default: `true`.
+ * @param allowMissingColumns Whether to allow rows with fewer columns than the header. Default: `true`.
  *
  *   If `true`, rows that are too short will be interpreted as _empty_ values.
  * @param ignoreExcessColumns Whether to ignore rows with more columns than the header. Default: `true`.
@@ -289,7 +289,7 @@ public fun DataFrame.Companion.readCsv(
  * @param parseParallel Whether to parse the data in parallel. Default: `true`.
  *
  *   If `true`, the data will be read and parsed in parallel by the Deephaven parser.
- *   This is usually faster, but can be turned off for debugging.
+ *   This is usually faster but can be turned off for debugging.
  */
 public fun DataFrame.Companion.readCsv(
     file: File,
@@ -386,7 +386,7 @@ public fun DataFrame.Companion.readCsv(
  *
  *   Fixed-width columns can occur, for instance, in multi-space delimited data, where the columns are separated
  *   by multiple spaces instead of a single delimiter, so columns are visually aligned.
- *   Columns widths are determined by the header in the data (if present), or manually by setting
+ *   Column widths are determined by the header in the data (if present), or manually by setting
  *   [fixedColumnWidths].
  * @param fixedColumnWidths The fixed column widths. Default: empty list.
  *
@@ -423,7 +423,7 @@ public fun DataFrame.Companion.readCsv(
  * @param ignoreEmptyLines Whether to skip intermediate empty lines. Default: `false`.
  *
  *   If `false`, empty lines will be interpreted as having _empty_ values if [allowMissingColumns].
- * @param allowMissingColumns Wether to allow rows with fewer columns than the header. Default: `true`.
+ * @param allowMissingColumns Whether to allow rows with fewer columns than the header. Default: `true`.
  *
  *   If `true`, rows that are too short will be interpreted as _empty_ values.
  * @param ignoreExcessColumns Whether to ignore rows with more columns than the header. Default: `true`.
@@ -441,7 +441,7 @@ public fun DataFrame.Companion.readCsv(
  * @param parseParallel Whether to parse the data in parallel. Default: `true`.
  *
  *   If `true`, the data will be read and parsed in parallel by the Deephaven parser.
- *   This is usually faster, but can be turned off for debugging.
+ *   This is usually faster but can be turned off for debugging.
  */
 public fun DataFrame.Companion.readCsv(
     url: URL,
@@ -538,7 +538,7 @@ public fun DataFrame.Companion.readCsv(
  *
  *   Fixed-width columns can occur, for instance, in multi-space delimited data, where the columns are separated
  *   by multiple spaces instead of a single delimiter, so columns are visually aligned.
- *   Columns widths are determined by the header in the data (if present), or manually by setting
+ *   Column widths are determined by the header in the data (if present), or manually by setting
  *   [fixedColumnWidths].
  * @param fixedColumnWidths The fixed column widths. Default: empty list.
  *
@@ -575,7 +575,7 @@ public fun DataFrame.Companion.readCsv(
  * @param ignoreEmptyLines Whether to skip intermediate empty lines. Default: `false`.
  *
  *   If `false`, empty lines will be interpreted as having _empty_ values if [allowMissingColumns].
- * @param allowMissingColumns Wether to allow rows with fewer columns than the header. Default: `true`.
+ * @param allowMissingColumns Whether to allow rows with fewer columns than the header. Default: `true`.
  *
  *   If `true`, rows that are too short will be interpreted as _empty_ values.
  * @param ignoreExcessColumns Whether to ignore rows with more columns than the header. Default: `true`.
@@ -593,7 +593,7 @@ public fun DataFrame.Companion.readCsv(
  * @param parseParallel Whether to parse the data in parallel. Default: `true`.
  *
  *   If `true`, the data will be read and parsed in parallel by the Deephaven parser.
- *   This is usually faster, but can be turned off for debugging.
+ *   This is usually faster but can be turned off for debugging.
  */
 public fun DataFrame.Companion.readCsv(
     fileOrUrl: String,
@@ -690,7 +690,7 @@ public fun DataFrame.Companion.readCsv(
  *
  *   Fixed-width columns can occur, for instance, in multi-space delimited data, where the columns are separated
  *   by multiple spaces instead of a single delimiter, so columns are visually aligned.
- *   Columns widths are determined by the header in the data (if present), or manually by setting
+ *   Column widths are determined by the header in the data (if present), or manually by setting
  *   [fixedColumnWidths].
  * @param fixedColumnWidths The fixed column widths. Default: empty list.
  *
@@ -727,7 +727,7 @@ public fun DataFrame.Companion.readCsv(
  * @param ignoreEmptyLines Whether to skip intermediate empty lines. Default: `false`.
  *
  *   If `false`, empty lines will be interpreted as having _empty_ values if [allowMissingColumns].
- * @param allowMissingColumns Wether to allow rows with fewer columns than the header. Default: `true`.
+ * @param allowMissingColumns Whether to allow rows with fewer columns than the header. Default: `true`.
  *
  *   If `true`, rows that are too short will be interpreted as _empty_ values.
  * @param ignoreExcessColumns Whether to ignore rows with more columns than the header. Default: `true`.
@@ -745,7 +745,7 @@ public fun DataFrame.Companion.readCsv(
  * @param parseParallel Whether to parse the data in parallel. Default: `true`.
  *
  *   If `true`, the data will be read and parsed in parallel by the Deephaven parser.
- *   This is usually faster, but can be turned off for debugging.
+ *   This is usually faster but can be turned off for debugging.
  * @param adjustCsvSpecs Optional extra [CsvSpecs] configuration. Default: `{ it }`.
  *
  *   Before instantiating the [CsvSpecs], the [CsvSpecs.Builder] will be passed to this lambda.

dataframe-csv/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readCsvStr.kt

@@ -70,7 +70,7 @@ import org.jetbrains.kotlinx.dataframe.impl.io.readDelimImpl
  *
  *   Fixed-width columns can occur, for instance, in multi-space delimited data, where the columns are separated
  *   by multiple spaces instead of a single delimiter, so columns are visually aligned.
- *   Columns widths are determined by the header in the data (if present), or manually by setting
+ *   Column widths are determined by the header in the data (if present), or manually by setting
  *   [fixedColumnWidths].
  * @param fixedColumnWidths The fixed column widths. Default: empty list.
  *
@@ -107,7 +107,7 @@ import org.jetbrains.kotlinx.dataframe.impl.io.readDelimImpl
  * @param ignoreEmptyLines Whether to skip intermediate empty lines. Default: `false`.
  *
  *   If `false`, empty lines will be interpreted as having _empty_ values if [allowMissingColumns].
- * @param allowMissingColumns Wether to allow rows with fewer columns than the header. Default: `true`.
+ * @param allowMissingColumns Whether to allow rows with fewer columns than the header. Default: `true`.
  *
  *   If `true`, rows that are too short will be interpreted as _empty_ values.
  * @param ignoreExcessColumns Whether to ignore rows with more columns than the header. Default: `true`.
@@ -125,7 +125,7 @@ import org.jetbrains.kotlinx.dataframe.impl.io.readDelimImpl
  * @param parseParallel Whether to parse the data in parallel. Default: `true`.
  *
  *   If `true`, the data will be read and parsed in parallel by the Deephaven parser.
- *   This is usually faster, but can be turned off for debugging.
+ *   This is usually faster but can be turned off for debugging.
  */
 public fun DataFrame.Companion.readCsvStr(
     text: String,