Move docstrings to respective functions

docs/src/index.md

@@ -1,15 +1,3 @@
 # MCMCChains
 
 Implementation of Julia types for summarizing MCMC simulations and utility functions for [diagnostics](@ref Diagnostics) and [visualizations](@ref StatsPlots.jl).
-
-```@docs
-ridgelineplot(chains::Chains, par_names::Vector{Symbol}; hpd_val = [0.05, 0.2],
-q = [0.1, 0.9], spacer = 0.5, _riser = 0.2, show_mean = true, show_median = true,
-show_qi = false, show_hpdi = true, fill_q = true, fill_hpd = false, ordered = false)
-```
-
-```@docs
-forestplot(chains::Chains, par_names::Vector{Symbol}; hpd_val = [0.05, 0.2], q = [0.1, 0.9],
-spacer = 0.5, _riser = 0.2, show_mean = true, show_median = true, show_qi = false,
-show_hpdi = true, fill_q = true, fill_hpd = false, ordered = false)
-```

docs/src/statsplots.md

@@ -30,13 +30,11 @@ savefig(filename); nothing # hide
 ```
 
 ![Default plot for Chains](default_plot.svg)
-\
 
 ```@example statsplots
 plot(chn, colordim = :parameter; size=(840, 400))
 ```
 
-\
 Note that the plot function takes the additional arguments described in the [Plots.jl](https://github.com/JuliaPlots/Plots.jl) package.
 
 ## Mixed density
@@ -91,78 +89,31 @@ autocorplot(chn)
 corner(chn)
 ```
 
-For plotting multiple parameters, Ridgeline, Forest and Caterpillar plots can be useful.
-Please see the docstrings for a detailed description of these functions.
+For plotting multiple parameters, ridgeline, forest and caterpillar plots can be useful.
 
 ## Ridgeline
 
 ```@example statsplots
 ridgelineplot(chn, [:C, :B, :A])
 ```
-""""
-    ridgelineplot(chains::Chains, par_names::Vector{Symbol}; hpd_val = [0.05, 0.2],
-    q = [0.1, 0.9], spacer = 0.5, _riser = 0.2, show_mean = true, show_median = true,
-    show_qi = false, show_hpdi = true, fill_q = true, fill_hpd = false, ordered = false)
-
-Given a `chains` object, returns a Ridgeline plot for the sampled parameters specified on
-`par_names`.
-
-For ridgeline plots, the following parameters are defined:
-
-** (a) Fill **
-Fill area below the curve can be determined by quantiles interval (`fill_q = true`) or
-hdpi interval (`fill_hpd = true`). Default options are `fill_hpd = true` and `fill_q = false`.
-If both `fill_q = false` and `fill_hpd = false`, then the whole area below the curve will be
-filled. If no fill color is desired, it should be specified with series attributes. These
-fill options are mutually exclusive.
-
-** (b) Mean and median **
-A vertical line can be plotted repesenting the mean (`show_mean = true`) or median
-(`show_median = true`) of the density (kde) distribution. Both options can be plotted at the
- same time.
-
-** (c) Intervals **
-At the bottom of each density plot, a quantile interval (`show_qi = true`) or HPD interval
-(`show_hdpi = true`) can be plotted. These options are mutually exclusive. Default options
-are `show_qi = false` and `show_hpdi = true`.To plot quantile intervals, the values specified
-as `q` will be taken, and for HPD intervals, only the smaller value specified in `hpd_val`
-will be used.
-
-Note: When one parameter is given, it will be plotted as a density plot with all the elements
-described above.
-"""
 
 ## Forest
 
 ```@example statsplots
 forestplot(chn, [:C, :B, :A], hpd_val = [0.05, 0.15, 0.25])
 ```
 
-"""
-    forestplot(chains::Chains, par_names::Vector{Symbol}; hpd_val = [0.05, 0.2],
-    q = [0.1, 0.9], spacer = 0.5, _riser = 0.2, show_mean = true, show_median = true,
-    show_qi = false, show_hpdi = true, fill_q = true, fill_hpd = false, ordered = false)
-
-Given a `chains` object, returns a Forest plot for the sampled parameters specified on
-`par_names`.
-
-Both `forest` and `caterpillar` plots are called using `forestplot` shorthands.
-If `ordered = false`, then a `forest` plot will be returned, and if `ordered = true`,
-a `caterpillar` plot will be returned.
-
-For both plot types the following elemets can be plotted:
-
-**High posterior density intervals (HPDI)** determined by the number of elements in `hpd_val`.
-All the values in `hpd_val` will be used to construct the intervals with `MCMCChains.hpd.
-
-**Quantile intervals** determined by the 2-element vector `q`.
-
-**Mean and/or median.** Plotted as points with different `markershape..
-
-"""
-
 ## Caterpillar
 
 ```@example statsplots
 forestplot(chn, chn.name_map[:parameters], hpd_val = [0.05, 0.15, 0.25], ordered = true)
 ```
+
+## API
+
+```@docs
+ridgelineplot
+ridgelineplot!
+forestplot
+forestplot!
+```

src/plot.jl

@@ -4,7 +4,72 @@
 @shorthands pooleddensity
 @shorthands traceplot
 @shorthands corner
+
+"""
+    ridgelineplot(chains::Chains[, params::Vector{Symbol}]; kwargs...)
+
+Generate a ridgeline plot for the samples of the parameters `params` in `chains`.
+
+By default, all parameters are plotted.
+
+## Keyword arguments
+
+The following options are available:
+
+- `fill_q` (default: `false`) and `fill_hpd` (default: `true`):
+  Fill the area below the curve in the quantiles interval (`fill_q = true`) or the highest posterior density (HPD) interval (`fill_hpd = true`).
+  If both `fill_q = false` and `fill_hpd = false`, then the whole area below the curve is filled.
+  If no fill color is desired, it should be specified with series attributes.
+  These options are mutually exclusive.
+
+- `show_mean` (default: `true`) and `show_median` (default: `true`):
+  Plot a vertical line of the mean (`show_mean = true`) or median (`show_median = true`) of the posterior density estimate.
+  If both options are set to `true`, both lines are plotted.
+
+- `show_qi` (default: `false`) and `show_hpdi` (default: `true`):
+  Plot a quantile interval (`show_qi = true`) or the largest HPD interval (`show_hpdi = true`) at the bottom of each density plot.
+  These options are mutually exclusive.
+
+- `q` (default: `[0.1, 0.9]`): The two quantiles used for plotting if `fill_q = true` or `show_qi = true`.
+
+- `hpd_val` (default: `[0.05, 0.2]`): The complementary probability mass(es) of the highest posterior density intervals that are plotted if `fill_hpd = true` or `show_hpdi = true`.
+
+!!! note
+    If a single parameter is provided, the generated plot is a density plot with all the elements described above.
+"""
 @userplot RidgelinePlot
+
+"""
+    forestplot(chains::Chains[, params::Vector{Symbol}]; kwargs...)
+
+Generate a forest or caterpillar plot for the samples of the parameters `params` in `chains`.
+
+By default, all parameters are plotted.
+
+## Keyword arguments
+
+- `ordered` (default: `false`):
+  If `ordered = false`, a forest plot is generated.
+  If `ordered = true`, a caterpillar plot is generated.
+
+- `fill_q` (default: `false`) and `fill_hpd` (default: `true`):
+  Fill the area below the curve in the quantiles interval (`fill_q = true`) or the highest posterior density (HPD) interval (`fill_hpd = true`).
+  If both `fill_q = false` and `fill_hpd = false`, then the whole area below the curve is filled.
+  If no fill color is desired, it should be specified with series attributes.
+  These options are mutually exclusive.
+
+- `show_mean` (default: `true`) and `show_median` (default: `true`):
+  Plot a vertical line of the mean (`show_mean = true`) or median (`show_median = true`) of the posterior density estimate.
+  If both options are set to `true`, both lines are plotted.
+
+- `show_qi` (default: `false`) and `show_hpdi` (default: `true`):
+  Plot a quantile interval (`show_qi = true`) or the largest HPD interval (`show_hpdi = true`) at the bottom of each density plot.
+  These options are mutually exclusive.
+
+- `q` (default: `[0.1, 0.9]`): The two quantiles used for plotting if `fill_q = true` or `show_qi = true`.
+
+- `hpd_val` (default: `[0.05, 0.2]`): The complementary probability mass(es) of the highest posterior density intervals that are plotted if `fill_hpd = true` or `show_hpdi = true`.
+"""
 @userplot ForestPlot
 
 struct _TracePlot; c; val; end