Add input validation

doc/syntax/clause/facet.qmd

@@ -34,7 +34,7 @@ This clause behaves much like the `SETTINGS` clause in `DRAW`, in that it allows
   * `'y'`: Shared x-axis scale, independent y-axis scale
   * `['x', 'y']`: Independent scales for both axes
 * `missing`: Determines how layers behave when the faceting column is missing. It can take two values: `'repeat'` (default), and `'null'`. If `'repeat'` is set, then the layer data is repeated in each panel. If `'null'`, then such layers are only displayed if a null panel is shown, as controlled by the facet scale.
-* `ncol`/`nrow`: The dimensions of the layout when faceting by a single variable. Only one of these can be given, as the other is derived based on the number of panels to draw. Default is 3 columns when fewer than 6 categories are present, 4 columns when fewer than 12 categories are present and otherwise 5 columns. When the `BY`-clause is used to set a second faceting variable, the `ncol` and `nrow` setting are not allowed.
+* `ncol`/`nrow`: The dimensions of the layout when faceting by a single variable (whole number >= 1). Only one of these can be given, as the other is derived based on the number of panels to draw. Default is 3 columns when fewer than 6 categories are present, 4 columns when fewer than 12 categories are present and otherwise 5 columns. When the `BY`-clause is used to set a second faceting variable, the `ncol` and `nrow` setting are not allowed.
 
 ### Facet variables as aesthetics
 When you apply faceting to a plot you are creating new aesthetics you can control. For 1-dimensional faceting (no `BY` clause) the aesthetic is called `panel` and for 2-dimensional faceting the aesthetics are called `row` and `column`. You can read more about these aesthetics in [their documentation](../scale/aesthetic/Z_faceting.qmd)

doc/syntax/coord/cartesian.qmd

@@ -20,7 +20,7 @@ assuming they do not try to use a name that is already being used by any facet o
 
 ## Settings
 * `clip`: Should data be removed if it appears outside the bounds of the coordinate system. Defaults to `true`
-* `ratio`: The aspect ratio between the steps on the vertical and horizontal axis. Defaults to `null` (no enforced aspect ratio)
+* `ratio`: The aspect ratio between the steps on the vertical and horizontal axis (must be > 0 if specified). Defaults to `null` (no enforced aspect ratio)
 
 ## Examples
 

doc/syntax/coord/polar.qmd

@@ -20,12 +20,12 @@ This maps `y` to radius and `x` to angle. This is useful when converting from a
 
 ## Settings
 * `clip`: Should data be removed if it appears outside the bounds of the coordinate system. Defaults to `true`
-* `start`: The starting angle in degrees for the angle scale. Controls where "0" on the angular axis begins. Defaults to `0` (12 o'clock position).
+* `start`: The starting angle in degrees for the theta scale (-360 to 360). Controls where "0" on the angular axis begins. Defaults to `0` (12 o'clock position).
   - `0` = 12 o'clock position (top)
   - `90` = 3 o'clock position (right)
   - `-90` or `270` = 9 o'clock position (left)
   - `180` = 6 o'clock position (bottom)
-* `end`: The ending angle in degrees for the angle scale. Defaults to `start + 360` (a full circle). Use this with `start` to create partial polar plots like gauge charts or half-circle visualizations.
+* `end`: The ending angle in degrees for the theta scale (-360 to 360). Defaults to `start + 360` (a full circle). Use this with `start` to create partial polar plots like gauge charts or half-circle visualizations.
 * `inner`: The inner radius as a proportion (0 to 1) of the outer radius. Defaults to `0` (no hole). Setting this creates a donut chart where the inner portion is empty.
   - `0` = full pie (no hole)
   - `0.3` = donut with 30% hole

doc/syntax/layer/position/dodge.qmd

@@ -12,7 +12,7 @@ Dodge doesn't have specific requirements to the scale type of the plot, but will
 ## Settings
 Apart from the settings of the layer type, setting `position => 'dodge'` will allow these additional settings:
 
-* `width`: The total width the dodging will occupy as a proportion of the space available on the scale. Defaults to 0.9 but any defaults from the layer will take precedence.
+* `width`: The total width the dodging will occupy as a proportion of the space available on the scale (0 to 1). Defaults to 0.9 but any defaults from the layer will take precedence.
 
 ## Examples
 

doc/syntax/layer/position/jitter.qmd

@@ -12,17 +12,17 @@ Jitter requires at least one axis to be discrete as it only jitters along discre
 ## Settings
 Apart from the settings of the layer type, setting `position => 'jitter'` will allow these additional settings:
 
-* `width`: The total width the jittering will occupy as a proportion of the space available on the scale. Defaults to 0.9
+* `width`: The total width the jittering will occupy as a proportion of the space available on the scale (0 to 1). Defaults to 0.4
 * `dodge`: Should dodging be applied before jittering. The dodging behavior follows the [dodge position](dodge.qmd) behavior? Default to `true`
 * `distribution`: Which kind of distribution should the jittering follow? One of:
   - `'uniform'` (default): Jittering is sampled from a uniform distribution between `-width/2` and `width/2`
   - `'normal'`: Jittering is sampled from a normal distribution with σ as `width/4` resulting in 95% of the points falling inside the given width
   - `'density'`: Jittering follows the density distribution within the group so that the jitter occupies the same area as an equivalent [violin plot](../type/violin.qmd) with density remapped to offset
   - `'intensity'`: Jittering follows the intensity distribution within the group so that the jitter occupies the same area as an equivalent [violin plot](../type/violin.qmd) with intensity remapped to offset
-  
+
   If `distribution` is either `'density'` or `'intensity'` then one of the axes must be continuous
-* `bandwidth`: A numerical value setting the smoothing bandwidth to use for the `'density'` and `'intensity'` distributions. If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
-* `adjust`: A numerical value as multiplier for the `bandwidth` setting, with 1 as default.
+* `bandwidth`: Smoothing bandwidth for the `'density'` and `'intensity'` distributions (must be > 0). If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
+* `adjust`: Multiplier for the `bandwidth` setting (must be > 0). Defaults to 1.
 
 ## Examples
 When plotting points on a discrete axis they are all placed in the middle

doc/syntax/layer/position/stack.qmd

@@ -13,7 +13,7 @@ Stack requires a continuous scale with a range mapping (e.g. either `y` + `yend`
 Apart from the settings of the layer type, setting `position => 'stack'` will allow these additional settings:
 
 * `center`: Should the full stack be centered around 0. Can be used in conjunction with area layers to create steamgraphs. Default to `false`
-* `total`: Sets a total value to which each stack height is normalised. Setting this value leads to 'fill' behaviour. Defaults to `null` (no normalisation)
+* `total`: Sets a total value to which each stack height is normalised (must be > 0 if specified). Setting this value leads to 'fill' behaviour. Defaults to `null` (no normalisation)
 
 ## Examples
 

doc/syntax/layer/type/area.qmd

@@ -21,8 +21,8 @@ The following aesthetics are recognised by the area layer.
 * `linewidth`: The width of the contour lines.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'stack'`)
-* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following: 
+* `position`: Position adjustment. One of `'identity'`, `'stack'` (default), `'dodge'`, or `'jitter'`
+* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following:
     * `'aligned'` to align the layer's primary axis with the coordinate system's first axis.
     * `'transposed'` to align the layer's primary axis with the coordinate system's second axis.
 

doc/syntax/layer/type/bar.qmd

@@ -23,8 +23,8 @@ The bar layer has no required aesthetics
 * `linetype`: The type of stroke, i.e. the dashing pattern
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'stack'`)
-* `width`: The width of the bars as a proportion of the available width
+* `position`: Position adjustment. One of `'identity'`, `'stack'` (default), `'dodge'`, or `'jitter'`
+* `width`: The width of the bars as a proportion of the available width (0 to 1)
 
 ## Data transformation
 If the secondary axis has not been mapped the layer will calculate counts for you and display these as the secondary axis.

doc/syntax/layer/type/boxplot.qmd

@@ -23,10 +23,10 @@ The following aesthetics are recognised by the boxplot layer.
 * `shape` The shape of outlier points.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'dodge'`)
+* `position`: Position adjustment. One of `'identity'`, `'stack'`, `'dodge'` (default), or `'jitter'`
 * `outliers`: Whether to display outliers as points. Defaults to `true`.
-* `coef`: A number indicating the length of the whiskers as a multiple of the interquartile range (IQR). Defaults to `1.5`.
-* `width`: Relative width of the boxes. Defaults to `0.9`.
+* `coef`: Length of the whiskers as a multiple of the IQR (must be >= 0). Defaults to `1.5`.
+* `width`: Relative width of the boxes (0 to 1). Defaults to `0.9`.
 
 ## Data transformation
 Per group, data will be divided into 4 quartiles and summary statistics will be derived from their extremes. 

doc/syntax/layer/type/density.qmd

@@ -21,9 +21,9 @@ The following aesthetics are recognised by the density layer.
 * `linetype` The dash pattern of the contour line.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
-* `bandwidth`: A numerical value setting the smoothing bandwidth to use. If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
-* `adjust`: A numerical value as multiplier for the `bandwidth` setting, with 1 as default.
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
+* `bandwidth`: Smoothing bandwidth (must be > 0). If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
+* `adjust`: Multiplier for the `bandwidth` setting (must be > 0). Defaults to 1.
 * `kernel`: Determines the smoothing kernel shape. Can be one of the following:
     * `'gaussian'` (default)
     * `'epanechnikov'`

doc/syntax/layer/type/errorbar.qmd

@@ -21,7 +21,7 @@ The following aesthetics are recognised by the errorbar layer.
 * `linetype`: The dash pattern of the lines in the errorbar.
 
 ## Settings
-* `width`: The width of the hinges in points. Can be set to `null` to not display hinges.
+* `width`: The width of the hinges in points (must be >= 0). Defaults to 10. Can be set to `null` to not display hinges.
 
 ## Data transformation
 The errorbar layer does not transform its data but passes it through unchanged.

doc/syntax/layer/type/histogram.qmd

@@ -21,9 +21,9 @@ The following aesthetics are recognised by the bar layer.
 * `linetype`: The type of stroke, i.e. the dashing pattern
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'stack'`)
-* `bins`: The number of bins to calculate. Defaults to `30`
-* `binwidth`: The width of each bin. If provided it will override the binwidth calculated from `bins`
+* `position`: Position adjustment. One of `'identity'`, `'stack'` (default), `'dodge'`, or `'jitter'`
+* `bins`: The number of bins to calculate. Whole number >= 1. Defaults to `30`
+* `binwidth`: The width of each bin (must be > 0). If provided it will override the binwidth calculated from `bins`
 * `closed`: Either `'left'` or `'right'` (default). Determines whether the bin intervals are closed to the left or right side
 
 ## Data transformation

doc/syntax/layer/type/line.qmd

@@ -20,8 +20,8 @@ The following aesthetics are recognised by the line layer.
 * `linetype`: The type of line, i.e. the dashing pattern
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
-* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following: 
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
+* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following:
     * `'aligned'` to align the layer's primary axis with the coordinate system's first axis.
     * `'transposed'` to align the layer's primary axis with the coordinate system's second axis.
 

doc/syntax/layer/type/path.qmd

@@ -20,7 +20,7 @@ The following aesthetics are recognised by the path layer.
 * `linetype`: The type of path, i.e. the dashing pattern
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ## Data transformation
 The path layer does not transform its data but passes it through unchanged

doc/syntax/layer/type/point.qmd

@@ -22,7 +22,7 @@ The following aesthetics are recognised by the point layer.
 * `shape`: The shape used to draw the point
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ## Data transformation
 The point layer does not transform its data but passes it through unchanged

doc/syntax/layer/type/polygon.qmd

@@ -22,7 +22,7 @@ The following aesthetics are recognised by the polygon layer.
 * `linetype` The dash pattern of the contour line.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ## Data transformation
 The polygon layer does not transform its data but passes it through unchanged

doc/syntax/layer/type/rect.qmd

@@ -36,7 +36,7 @@ Alternatively, use only the center, which will set `height` to 1 by default.
 * `linetype`: The dash pattern of the contour line.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ## Data transformation.
 When the primary aesthetics are continuous, primary data is reparameterised to {start, end}, e.g. `xmin` and `xmax`.

doc/syntax/layer/type/ribbon.qmd

@@ -22,7 +22,7 @@ The following aesthetics are recognised by the ribbon layer.
 * `linewidth`: The width of the contour lines.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ## Data transformation
 The ribbon layer sorts the data along its primary axis

doc/syntax/layer/type/segment.qmd

@@ -25,7 +25,7 @@ If one is missing, it takes on the value of the start point.
 * `linetype`: The type of the line, i.e. the dashing pattern.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ## Data transformation
 The segment layer does not transform its data but passes it through unchanged.

doc/syntax/layer/type/smooth.qmd

@@ -26,8 +26,8 @@ Smooth layers are used to display a trendline among a series of observations.
     * `'tls'` estimates a straight trendline using total least squares method.
 
 The settings below only apply when `method => 'nw'` and are ignored when using other methods.
-* `bandwidth`: A numerical value setting the smoothing bandwidth to use. If absent (default), the bandwidth will be computed using Silverman's rule of thumb. 
-* `adjust`: A numerical value as multiplier for the `bandwidth` setting, with 1 as default.
+* `bandwidth`: Smoothing bandwidth (must be > 0). If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
+* `adjust`: Multiplier for the `bandwidth` setting (must be > 0). Defaults to 1.
 * `kernel`: Determines the smoothing kernel shape. Can be one of the following:
     * `'gaussian'` (default)
     * `'epanechnikov'`

doc/syntax/layer/type/text.qmd

@@ -32,9 +32,9 @@ The following aesthetics are recognised by the text layer.
 ## Settings
 * `offset` Position offset expressed in absolute points. Can be one of the following:
     * a single number that applies both horizontally and vertically
-    * an numeric array `[h, v]` where the first number is the horizontal offset and the second number is the vertical offset.
+    * a 2-element numeric array `[h, v]` where the first number is the horizontal offset and the second number is the vertical offset.
 * `format` Formatting specifier, see explanation below.
-* `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ### Format
 The `format` setting can take a string that will be used in formatting the `label` aesthetic. 

doc/syntax/layer/type/violin.qmd

@@ -23,18 +23,18 @@ The following aesthetics are recognised by the violin layer.
 * `linetype` The dash pattern of the contour line.
 
 ## Settings
-* `position`: Determines the position adjustment to use for the layer (default is `'dodge'`)
-* `bandwidth`: A numerical value setting the smoothing bandwidth to use. If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
-* `adjust`: A numerical value as multiplier for the `bandwidth` setting, with 1 as default.
+* `position`: Position adjustment. One of `'identity'`, `'stack'`, `'dodge'` (default), or `'jitter'`
+* `bandwidth`: Smoothing bandwidth (must be > 0). If absent (default), the bandwidth will be computed using Silverman's rule of thumb.
+* `adjust`: Multiplier for the `bandwidth` setting (must be > 0). Defaults to 1.
 * `kernel`: Determines the smoothing kernel shape. Can be one of the following:
     * `'gaussian'` (default)
     * `'epanechnikov'`
     * `'triangular'`
     * `'rectangular'` or `'uniform'`
     * `'biweight'` or `'quartic'`
     * `'cosine'`
-* `width`: Relative width of the violins. Defaults to `0.9`.
-* `tails`: Expansion rule for drawing the tails. One of the following:
+* `width`: Relative width of the violins (0 to 1). Defaults to `0.9`.
+* `tails`: Expansion rule for drawing the tails (must be >= 0 if numeric). One of the following:
     * A number setting a multiple of adjusted bandwidths to expand each group's range. Defaults to 3.
     * `null` to use the whole data range rather than group ranges.