Updates and fixes in KDocs.

Author: ASmirnov-HORIS

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/annotations/AnnotationOptions.kt

@@ -11,14 +11,14 @@ typealias AnnotationOptions = layerLabels
 
 
 /**
-* Configure annotations for geometry layers.
+ * Configure annotations for geometry layers.
  *
  * Annotations are currently supported for bar, pie, and crossbar geometry
  * layers. This class provides methods to customize the appearance and
  * content of text labels displayed on these geometries.
  *
- * Notes
- * -----
+ * ## Notes
+ *
  * By default, annotation text color is automatically selected for optimal
  * contrast: white text appears on darker filled geometries, and black text
  * appears on lighter filled geometries.
@@ -137,6 +137,14 @@ class layerLabels(vararg variables: String) {
         return setOption(ANNOTATION_SIZE, value)
     }
 
+
+    /**
+     * Use the layer's color for the annotation text.
+     *
+     * When enabled, the annotation text will inherit the color from the
+     * layer it's associated with, rather than using a default or
+     * explicitly set color.
+     */
     fun inheritColor(): layerLabels {
         return setOption(USE_LAYER_COLOR, true)
     }

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/bistro/corr/CorrPlot.kt

@@ -36,7 +36,7 @@ import kotlin.math.min
 /**
  * Correlation plot builder.
  *
- * The terminal `build()` method will create a fully configured 'Plot' (i.e. Figure) object.
+ * The terminal `build()` method will create a fully configured 'Plot' (i.e., Figure) object.
  *
  * ## Notes
  *

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/bistro/waterfall/WaterfallPlot.kt

@@ -25,7 +25,8 @@ package org.jetbrains.letsPlot.bistro.waterfall
  * @param x Name of a variable.
  * @param y Name of a numeric variable.
  * @param measure Kind of a calculation.
- *  Values in 'measure' column could be:
+ * It takes the name of a data column.
+ * The values in the column could be:
  *  - "absolute" - the value is shown as is;
  *  - "relative" - the value is shown as a difference from the previous value;
  *  - "total" - the value is shown as a cumulative sum of all previous values.
@@ -35,9 +36,13 @@ package org.jetbrains.letsPlot.bistro.waterfall
  * @param color Color of the box boundary lines.
  *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  *  Use "flow_type" to color lines by the direction of the flow.
+ *  Flow type names: "Absolute", "Increase", "Decrease" and "Total".
+ *  You could use these names to change the default colors with the `scaleColorManual()` function.
  * @param fill Fill color of the boxes.
  *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  *  Use "flow_type" to color boxes by the direction of the flow.
+ *  Flow type names: "Absolute", "Increase", "Decrease" and "Total".
+ *  You could use these names to change the default colors with the `scaleFillManual()` function.
  * @param size default = 0.0.
  *  Line width of the box boundary lines.
  * @param alpha Transparency level of the boxes. Understands numbers between 0 and 1.

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_bar.kt

@@ -23,18 +23,18 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
 
 @Suppress("ClassName")
 /**
- * Displays a bar chart which makes the height of the bar proportional to the number of observed variable values, mapped to x-axis.
+ * Display a bar chart which makes the height of the bar proportional to the number of observed variable values, mapped to the x-axis.
  *
  * ## Notes
  *
  * Computed variables:
  *
- * - ..count.. : number of points with same x-axis coordinate.
- * - ..sum.. : total number of points with same x-axis coordinate.
+ * - ..count.. : number of points with the same x-axis coordinate.
+ * - ..sum.. : total number of points with the same x-axis coordinate.
  * - ..prop.. : groupwise proportion.
  * - ..proppct.. : groupwise proportion in percent.
- * - ..sumprop.. : proportion of points with same x-axis coordinate among all points in the dataset.
- * - ..sumpct.. : proportion of points with same x-axis coordinate among all points in the dataset in percent.
+ * - ..sumprop.. : proportion of points with the same x-axis coordinate among all points in the dataset.
+ * - ..sumpct.. : proportion of points with the same x-axis coordinate among all points in the dataset in percent.
  *
  * To hide axis tooltips, set "blank" or the result of `elementBlank()`
  * to the `axisTooltip` or `axisTooltipX` parameter of the `theme()`.

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_bin2d.kt

@@ -74,7 +74,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  *  a hex string (up to 8 digits for dash-gap lengths),
  *  or a pattern `offset to listOf(dash, gap, ...)` / `listOf(dash, gap, ...)`.
  *  For more info see: [aesthetics.html#line-types](https://lets-plot.org/kotlin/aesthetics.html#line-types).
- * @param size Line width, default = 0 (i.e. tiles outline initially is not visible).
+ * @param size Line width, default = 0 (i.e., tiles outline initially is not visible).
  * @param weight Used by `Stat.bin2D()`stat to compute weighted sum instead of simple count.
  * @param colorBy default = "color" ("fill", "color", "paint_a", "paint_b", "paint_c").
  *  Defines the color aesthetic for the geometry.

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_blank.kt

@@ -68,8 +68,12 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  * @param size Size of the point.
  * @param stroke Width of the shape border. Applied only to the shapes having border.
  * @param angle Rotation angle of the shape, in degrees.
- * @param sizeUnit Relates the size of the point to the length of the unit step along one of the axes.
- *  Possible values: "x", "y". If not specified, no fitting is performed.
+ * @param sizeUnit ("x", "y", "min", "max").
+ *  Relate the size of the geom to the length of the unit step along one of the axes.
+ *  "x" uses the unit step along the x-axis, "y" uses the unit step along the y-axis.
+ *  "min" uses the smaller of the unit steps along the x- and y-axes.
+ *  "max" uses the larger of the unit steps along the x- and y-axes.
+ *  If not specified, no fitting is performed.
  * @param colorBy default = "color" ("fill", "color", "paint_a", "paint_b", "paint_c").
  *  Defines the color aesthetic for the geometry.
  * @param fillBy default = "fill" ("fill", "color", "paint_a", "paint_b", "paint_c").

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_contour.kt

@@ -20,7 +20,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
 
 @Suppress("ClassName")
 /**
- * Displays contours of a 3d surface in 2d.
+ * Displays contours of a 3D surface in 2D.
  *
  * ## Notes
  *

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_contourf.kt

@@ -20,7 +20,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
 
 @Suppress("ClassName")
 /**
- * Fills contours of a 3d surface in 2d.
+ * Fills contours of a 3D surface in 2D.
  *
  * ## Notes
  *

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_count.kt

@@ -17,9 +17,9 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  *
  * Computed variables:
  *
- * - ..n.. : number of points with same x-axis and y-axis coordinates.
- * - ..prop.. : proportion of points with same x-axis and y-axis coordinates.
- * - ..proppct.. : proportion of points with same x-axis and y-axis coordinates in percent.
+ * - ..n.. : number of points with the same x-axis and y-axis coordinates.
+ * - ..prop.. : proportion of points with the same x-axis and y-axis coordinates.
+ * - ..proppct.. : proportion of points with the same x-axis and y-axis coordinates in percent.
  *
  * To hide axis tooltips, set "blank" or the result of `elementBlank()`
  * to the `axisTooltip`, `axisTooltipX` or `axisTooltipY` parameter of the `theme()`.

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_density2d.kt

@@ -60,7 +60,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  *  or a Double array of length 2.
  * @param n The number of sampled points for plotting the function (on x and y direction correspondingly).
  * @param adjust Adjusts the value of bandwidth by multiplying it. Changes how smooth the frequency curve is.
- * @param contour If true, contour the results of the 2d density estimation.
+ * @param contour If true, contour the results of the 2D density estimation.
  * @param bins Number of levels.
  * @param binWidth Distance between levels.
  * @param weight Used by density stat to compute weighted density.