Add comprehensive KDoc documentation to all intern stat layer files with standardized format (#286)

Author: Copilot

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/Bin2dStatAesthetics.kt

@@ -9,7 +9,14 @@ import org.jetbrains.letsPlot.intern.Options
 import org.jetbrains.letsPlot.intern.OptionsCapsule
 
 /**
- * 'bin2d' stat requires x,y (weight is optional)
+ * Aesthetic properties supported by [statBin2D()][org.jetbrains.letsPlot.stat.statBin2D].
+ *
+ * ## Notes
+ * The bin2d stat requires x,y (weight is optional)
+ *
+ * @property x X-axis value.
+ * @property y Y-axis value.
+ * @property weight Used by `Stat.bin2D()`stat to compute weighted sum instead of simple count.
  */
 interface Bin2dStatAesthetics : OptionsCapsule {
     val x: Any?

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/Bin2dStatMapping.kt

@@ -5,6 +5,13 @@
 
 package org.jetbrains.letsPlot.intern.layer.stat
 
+/**
+ * Aesthetic mappings supported by [statBin2D()][org.jetbrains.letsPlot.stat.statBin2D].
+ *
+ * @param x X-axis value.
+ * @param y Y-axis value.
+ * @param weight Used by `Stat.bin2D()`stat to compute weighted sum instead of simple count.
+ */
 class Bin2dStatMapping(
     override var x: Any? = null,
     override var y: Any? = null,

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/Bin2dStatParameters.kt

@@ -9,6 +9,14 @@ import org.jetbrains.letsPlot.core.spec.Option.Stat
 import org.jetbrains.letsPlot.intern.Options
 import org.jetbrains.letsPlot.intern.OptionsCapsule
 
+/**
+ * Properties for parameters of [statBin2D()][org.jetbrains.letsPlot.stat.statBin2D].
+ *
+ * @property bins Number of bins in both directions, vertical and horizontal. Overridden by `binWidth`.
+ * @property binWidth The width of the bins in both directions, vertical and horizontal. Overrides `bins`.
+ *  The default is to use bin widths that cover the entire range of the data.
+ * @property drop Specifies whether to remove all bins with 0 counts.
+ */
 interface Bin2dStatParameters : OptionsCapsule {
     val bins: Pair<Int, Int>?
     val binWidth: Pair<Number?, Number?>?

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/BinHexStatAesthetics.kt

@@ -4,7 +4,14 @@ import org.jetbrains.letsPlot.intern.Options
 import org.jetbrains.letsPlot.intern.OptionsCapsule
 
 /**
- * 'binhex' stat requires x,y (weight is optional)
+ * Aesthetic properties supported by the default stat of [geomHex()][org.jetbrains.letsPlot.geom.geomHex].
+ *
+ * ## Notes
+ * The binhex stat requires x,y (weight is optional)
+ *
+ * @property x X-axis value.
+ * @property y Y-axis value.
+ * @property weight Used to compute weighted sum instead of simple count.
  */
 interface BinHexStatAesthetics : OptionsCapsule {
     val x: Any?

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/BinHexStatMapping.kt

@@ -1,5 +1,12 @@
 package org.jetbrains.letsPlot.intern.layer.stat
 
+/**
+ * Aesthetic mappings supported by the default stat of [geomHex()][org.jetbrains.letsPlot.geom.geomHex].
+ *
+ * @param x X-axis value.
+ * @param y Y-axis value.
+ * @param weight Used to compute weighted sum instead of simple count.
+ */
 class BinHexStatMapping(
     override var x: Any? = null,
     override var y: Any? = null,

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/BinHexStatParameters.kt

@@ -4,6 +4,14 @@ import org.jetbrains.letsPlot.core.spec.Option.Stat
 import org.jetbrains.letsPlot.intern.Options
 import org.jetbrains.letsPlot.intern.OptionsCapsule
 
+/**
+ * Properties for parameters of the default stat of [geomHex()][org.jetbrains.letsPlot.geom.geomHex].
+ *
+ * @property bins Number of bins in both directions, vertical and horizontal. Overridden by `binWidth`.
+ * @property binWidth The width of the bins in both directions, vertical and horizontal. Overrides `bins`.
+ *  The default is to use bin widths that cover the entire range of the data.
+ * @property drop Specifies whether to remove all bins with 0 counts.
+ */
 interface BinHexStatParameters : OptionsCapsule {
     val bins: Pair<Int, Int>?
     val binWidth: Pair<Number?, Number?>?

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/BinStatAesthetics.kt

@@ -8,6 +8,12 @@ package org.jetbrains.letsPlot.intern.layer.stat
 import org.jetbrains.letsPlot.intern.Options
 import org.jetbrains.letsPlot.intern.OptionsCapsule
 
+/**
+ * Aesthetic properties supported by [statBin()][org.jetbrains.letsPlot.stat.statBin].
+ *
+ * @property x X-axis coordinates.
+ * @property weight Used to compute weighted sum instead of simple count.
+ */
 interface BinStatAesthetics : OptionsCapsule {
     val x: Any?
     val weight: Any?

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/BinStatMapping.kt

@@ -5,6 +5,12 @@
 
 package org.jetbrains.letsPlot.intern.layer.stat
 
+/**
+ * Aesthetic mappings supported by [statBin()][org.jetbrains.letsPlot.stat.statBin].
+ *
+ * @param x X-axis coordinates.
+ * @param weight Used to compute weighted sum instead of simple count.
+ */
 class BinStatMapping(
     override var x: Any? = null,
     override var weight: Any? = null

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/BinStatParameters.kt

@@ -9,6 +9,18 @@ import org.jetbrains.letsPlot.core.spec.Option
 import org.jetbrains.letsPlot.intern.Options
 import org.jetbrains.letsPlot.intern.OptionsCapsule
 
+/**
+ * Properties for parameters of [statBin()][org.jetbrains.letsPlot.stat.statBin].
+ *
+ * @property bins Number of bins. Overridden by `binWidth`.
+ * @property binWidth The width of the bins. The default is to use bin widths that cover
+ *  the entire range of the data. You should always override this value, exploring multiple widths
+ *  to find the best to illustrate the stories in your data.
+ * @property center Specifies x-value to align bin centers to.
+ * @property boundary Specifies x-value to align bin boundary (i.e., point between bins) to.
+ * @property threshold Only bins with a `..count..` greater than the threshold will be displayed.
+ *  This is useful for free scales in facets - use threshold=0 to make the plot take up the entire panel space.
+ */
 interface BinStatParameters : OptionsCapsule {
     val bins: Int?
     val binWidth: Number?

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/intern/layer/stat/BoxplotOutlierStatParameters.kt

@@ -9,6 +9,11 @@ import org.jetbrains.letsPlot.core.spec.Option
 import org.jetbrains.letsPlot.intern.Options
 import org.jetbrains.letsPlot.intern.OptionsCapsule
 
+/**
+ * Properties for parameters of [statBoxplot()][org.jetbrains.letsPlot.stat.statBoxplot].
+ *
+ * @property coef Length of the whiskers as multiple of IQR.
+ */
 interface BoxplotOutlierStatParameters : OptionsCapsule {
     @Suppress("SpellCheckingInspection")
     val coef: Number?  // Whisker IQR ratio