updates based on review

Author: thomasp85

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 theta (angle). This is useful when converting
 
 ## 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 theta 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 theta 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'`