Deprecate positionStack, positionFill. Moved "pos" package doc to packages.md

Author: alshan

demo/browser/src/main/kotlin/frontendContextDemo/scripts/PointsOverBars.kt

@@ -30,7 +30,7 @@ object PointsOverBars {
             }
 
             // points with count stat and `stack` position adjustment
-            val points = geomPoint(stat = Stat.count(), position = positionStack, size = 15.0) {
+            val points = geomPoint(stat = Stat.count(), position = positionStack(), size = 15.0) {
                 x = "cat1"
                 color = "cat2"
             }

demo/jvm-batik/src/main/kotlin/frontendContextDemo/scripts/PointsOverBars.kt

@@ -30,7 +30,7 @@ object PointsOverBars {
             }
 
             // points with count stat and `stack` position adjustment
-            val points = geomPoint(stat = Stat.count(), position = positionStack, size = 15.0) {
+            val points = geomPoint(stat = Stat.count(), position = positionStack(), size = 15.0) {
                 x = "cat1"
                 color = "cat2"
             }

demo/jvm-batik/src/main/kotlin/frontendContextDemo/scripts/PositionStackFill.kt

@@ -29,7 +29,7 @@ object PositionStackFill {
             (p + geomBar(stat = Stat.identity, color = "black") { fill = "grp" } +
                     geomLabel(position = positionStack(0.5)) { label = "y" }).show()
 
-            (p + geomBar(stat = Stat.identity, position = positionFill, color = "black") { fill = "grp" } +
+            (p + geomBar(stat = Stat.identity, position = positionFill(), color = "black") { fill = "grp" } +
                     geomText(position = positionFill(0.5)) { label = "y" }).show()
         }
     }

demo/jvm-javafx/src/main/kotlin/frontendContextDemo/scripts/PointsOverBars.kt

@@ -30,7 +30,7 @@ object PointsOverBars {
             }
 
             // points with count stat and `stack` position adjustment
-            val points = geomPoint(stat = Stat.count(), position = positionStack, size = 15.0) {
+            val points = geomPoint(stat = Stat.count(), position = positionStack(), size = 15.0) {
                 x = "cat1"
                 color = "cat2"
             }

docs/dokka/source/packages.md

@@ -98,7 +98,10 @@ See [formats.md](https://github.com/JetBrains/lets-plot-kotlin/blob/master/docs/
 
 # Package org.jetbrains.letsPlot.sampling
 
-Sampling options to pass as a value of `sampling` parameter of layer functions like:
+Sampling options.                
+
+Used as a value of the `sampling` parameter in `geom_xyz()` functions.
+
 
 ```kotlin
 val n = 100
@@ -157,4 +160,27 @@ See [tooltips.md](https://github.com/JetBrains/lets-plot-kotlin/blob/master/docs
 
 - [tooltip_title.ipynb](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/tooltip_title.ipynb)
 
-- [tooltips_theme.ipynb](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/tooltips_theme.ipynb)
+- [tooltips_theme.ipynb](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/tooltips_theme.ipynb)
+
+# Package org.jetbrains.letsPlot.pos
+
+Position adjustment options.
+
+Used as a value of the `position` parameter in `geom_xyz()` functions.
+
+```kotlin
+val n = 100
+val m = 5
+val k = 2
+val rand = java.util.Random(42)
+val data = mapOf(
+    "v" to List(n) { rand.nextInt(m) },
+    "c" to List(n) { rand.nextInt(k) }
+)
+letsPlot(data) +
+    geomBar(position = positionDodge()) { x="v"; fill=asDiscrete("c") }
+```
+
+## Examples
+
+- [error_bars.ipynb](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/error_bars.ipynb)

future_changes.md

@@ -17,6 +17,10 @@
 
 ### Changed
 
+- Deprecated API:
+  - `positionStack`, new usage: `positionStack()`
+  - `positionFill`, new usage: `positionFill()`
+
 - Upgraded Kotlin version to 1.7.20 (was 1.6.21).                    
 - Upgraded Lets-Plot version to 2.5.1 (was 2.5.0).
 

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

@@ -169,14 +169,14 @@ object Pos {
         ReplaceWith("positionStack", imports = ["org.jetbrains.letsPlot.pos.positionStack"]),
         level = DeprecationLevel.WARNING
     )
-    val stack = positionStack
+    val stack = positionStack()
 
     @Deprecated(
         "",
         ReplaceWith("positionFill", imports = ["org.jetbrains.letsPlot.pos.positionFill"]),
         level = DeprecationLevel.WARNING
     )
-    val fill = positionFill
+    val fill = positionFill()
 
     @Deprecated(
         "",

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

@@ -58,7 +58,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
 class geomArea(
     data: Map<*, *>? = null,
     stat: StatOptions = identity,
-    position: PosOptions = positionStack,
+    position: PosOptions = positionStack(),
     showLegend: Boolean = true,
     sampling: SamplingOptions? = null,
     tooltips: TooltipOptions? = null,

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

@@ -57,7 +57,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
 class geomBar(
     data: Map<*, *>? = null,
     stat: StatOptions = Stat.count(),
-    position: PosOptions = positionStack,
+    position: PosOptions = positionStack(),
     showLegend: Boolean = true,
     sampling: SamplingOptions? = null,
     tooltips: TooltipOptions? = null,

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

@@ -58,7 +58,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
 class geomHistogram(
     data: Map<*, *>? = null,
     stat: StatOptions = Stat.bin(),
-    position: PosOptions = positionStack,
+    position: PosOptions = positionStack(),
     showLegend: Boolean = true,
     sampling: SamplingOptions? = null,
     tooltips: TooltipOptions? = null,

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

@@ -12,37 +12,20 @@ import org.jetbrains.letsPlot.intern.Options
 import org.jetbrains.letsPlot.intern.PosKind
 import org.jetbrains.letsPlot.intern.layer.PosOptions
 
-/**
- * Pos options to pass as a value of `position` parameter of layer functions like:
- *
- * ```kotlin
- * val n = 100
- * val m = 5
- * val k = 2
- * val rand = java.util.Random(42)
- * val data = mapOf(
- *     "v" to List(n) { rand.nextInt(m) },
- *     "c" to List(n) { rand.nextInt(k) }
- * )
- * letsPlot(data) +
- *     geomBar(position=Pos.dodge) { x="v"; fill=asDiscrete("c") }
- * ```
- */
-private object Pos {
-//    val identity = PosOptions(PosKind.IDENTITY)
-//    val stack = PosOptions(PosKind.STACK)
-//    val dodge = PosOptions(PosKind.DODGE)
-//    val fill = PosOptions(PosKind.FILL)
-//    val nudge = PosOptions(PosKind.NUDGE)
-//    val jitter = PosOptions(PosKind.JITTER)
-
-//    @Suppress("SpellCheckingInspection")
-//    val jitterdodge = PosOptions(PosKind.JITTER_DODGE)
-
-}
-
 val positionIdentity = PosOptions(PosKind.IDENTITY)
+
+@Deprecated(
+    "",
+    ReplaceWith("positionStack()", imports = ["org.jetbrains.letsPlot.pos.positionStack()"]),
+    level = DeprecationLevel.WARNING
+)
 val positionStack = positionStack()
+
+@Deprecated(
+    "",
+    ReplaceWith("positionFill()", imports = ["org.jetbrains.letsPlot.pos.positionFill()"]),
+    level = DeprecationLevel.WARNING
+)
 val positionFill = positionFill()
 
 

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/stat/stat_bin.kt

@@ -22,7 +22,7 @@ import org.jetbrains.letsPlot.pos.positionStack
 class statBin(
     data: Map<*, *>? = null,
     geom: GeomOptions = Geom.histogram(),
-    position: PosOptions = positionStack,
+    position: PosOptions = positionStack(),
     showLegend: Boolean = true,
     sampling: SamplingOptions? = null,
     override val x: Number? = null,

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/stat/stat_count.kt

@@ -21,7 +21,7 @@ import org.jetbrains.letsPlot.pos.positionStack
 class statCount(
     data: Map<*, *>? = null,
     geom: GeomOptions = Geom.bar(),
-    position: PosOptions = positionStack,
+    position: PosOptions = positionStack(),
     showLegend: Boolean = true,
     sampling: SamplingOptions? = null,
     override val x: Number? = null,

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/stat/stat_density.kt

@@ -22,7 +22,7 @@ import org.jetbrains.letsPlot.pos.positionStack
 class statDensity(
     data: Map<*, *>? = null,
     geom: GeomOptions = GeomOptions(GeomKind.DENSITY),
-    position: PosOptions = positionStack,
+    position: PosOptions = positionStack(),
     showLegend: Boolean = true,
     sampling: SamplingOptions? = null,
     override val x: Number? = null,