rephrase docstrings to remove explicit Arguments section

docs/src/dev/regression.md

@@ -28,6 +28,6 @@ So the automated regression analysis workflow is then as follows:
 6. `Pkg.test` again,
 7. `Pkg.add("ArgParse")` and, for B&W images, Cairo, Fontconfig, Rsvg, and Images as well,
 8. check for differences with `julia test/compare_examples.jl [--diff] [--two]
-[--bw] [-h] [filter]`.  For example, `julia test/compare_examples.jl -bw
+[--bw] [-h] [filter]`.  For example, `julia test/compare_examples.jl --bw
 .js.svg` will show black and white images hightlighting the differences between
 the svg test images.

docs/src/gallery/geometries.md

@@ -63,10 +63,10 @@ plot(dataset("lattice", "singer"), x="VoicePart", y="Height", Geom.boxplot)
 ## Geom.contour
 
 ```@example
-using Gadfly, RDatasets
+using Gadfly
 set_default_plot_size(14cm, 8cm)
 plot(z=(x,y) -> x*exp(-(x-round(Int, x))^2-y^2),
-     x=linspace(-8,8,150), y=linspace(-2,2,150), Geom.contour)
+     xmin=[-8], xmax=[8], ymin=[-2], ymax=[2], Geom.contour)
 ```
 
 ```@example

docs/src/lib/statistics.md

@@ -5,7 +5,7 @@ Author = "Daniel C. Jones"
 # [Statistics](@id lib_stat)
 
 Statistics are functions taking as input one or more aesthetics, operating on
-those values, then output to one or more aesthetics. For example, drawing of
+those values, then outputting to one or more aesthetics. For example, drawing of
 boxplots typically uses the boxplot statistic ([`Stat.boxplot`](@ref)) that takes
 as input the `x` and `y` aesthetic, and outputs the middle, and upper and lower
 hinge, and upper and lower fence aesthetics.

src/Gadfly.jl

@@ -69,6 +69,15 @@ default_scales(x::Any, t) = default_scales(x)
 default_statistic(::Any) = Stat.identity()
 element_coordinate_type(::Any) = Coord.cartesian
 
+function aes2str(aes)
+  list = join([string('`',x,'`') for x in aes], ", ", " and ")
+  if length(aes)>1
+    return string(list," aesthetics")
+  else
+    return string(list," aesthetic")
+  end
+end
+
 
 abstract type Element end
 abstract type ScaleElement       <: Element end
@@ -102,7 +111,8 @@ const gadflyjs = joinpath(dirname(Base.source_path()), "gadfly.js")
 """
     set_default_plot_size(width::Compose.MeasureOrNumber, height::Compose.MeasureOrNumber)
 
-Sets preferred canvas size when rendering a plot without an explicit call to draw
+Sets preferred canvas size when rendering a plot without an explicit call to draw.  Units
+can be `inch`, `cm`, `mm`, `pt`, or `px`.
 """
 set_default_plot_size(width::Compose.MeasureOrNumber, height::Compose.MeasureOrNumber) =
         Compose.set_default_graphic_size(width, height)
@@ -111,7 +121,7 @@ set_default_plot_size(width::Compose.MeasureOrNumber, height::Compose.MeasureOrN
 """
     set_default_plot_format(fmt::Symbol)
 
-Sets the default plot format
+Sets the default plot format.  (NOT SURE THIS DOES ANYTHING.)
 """
 set_default_plot_format(fmt::Symbol) = Compose.set_default_graphic_format(fmt)
 
@@ -133,18 +143,15 @@ copy(l::Layer) = Layer(l)
 
 
 """
-    layer(data_source::@compat(Union{AbstractDataFrame, (@compat Void)}),
-          elements::ElementOrFunction...; mapping...)
+    layer(data_source::Union{AbstractDataFrame, Void}),
+          elements::ElementOrFunction...; mapping...) -> [Layers]
 
 Creates layers based on elements
 
-### Args
-* data_source: The data source as a dataframe
-* elements: The elements
-* mapping: mapping
-
-### Returns
-An array of layers
+# Args
+- data_source: The data source as a dataframe
+- elements: The elements
+- mapping: mapping
 """
 function layer(data_source::Union{AbstractDataFrame, (Void)},
                elements::ElementOrFunction...; mapping...)
@@ -244,35 +251,15 @@ add_plot_element!(p::Plot, f::Type{T}) where {T <: Element} = add_plot_element!(
 add_plot_element!(p::Plot, theme::Theme) = p.theme = theme
 
 
-# Create a new plot.
-#
-# Grammar of graphics style plotting consists of specifying a dataset, one or
-# more plot elements (scales, coordinates, geometries, etc), and binding of
-# aesthetics to columns or expressions of the dataset.
-#
-# For example, a simple scatter plot would look something like:
-#
-#     plot(my_data, Geom.point, x="time", y="price")
-#
-# Where "time" and "price" are the names of columns in my_data.
-#
-# Args:
-#   data_source: Data to be bound to aesthetics.
-#   mapping: Aesthetics symbols (e.g. :x, :y, :color) mapped to
-#            names of columns in the data frame or other expressions.
-#   elements: Geometries, statistics, etc.
-
 # because a call to layer() expands to a vector of layers (one for each Geom
 # supplied), we need to allow Vector{Layer} to count as an Element for the
 # purposes of plot().
 const ElementOrFunctionOrLayers = Union{ElementOrFunction, Vector{Layer}}
 
 
 """
-```
-    plot(data_source::@compat(Union{AbstractMatrix, AbstractDataFrame}),
+    plot(data_source::Union{AbstractMatrix, AbstractDataFrame},
          elements::ElementOrFunctionOrLayers...; mapping...)
-```
 
 Create a new plot.
 
@@ -282,14 +269,14 @@ aesthetics to columns or expressions of the dataset.
 
 For example, a simple scatter plot would look something like:
 
-plot(my_data, Geom.point, x="time", y="price")
+    plot(my_data, Geom.point, x=:time, y=:price)
 
-Where "time" and "price" are the names of columns in my_data.
+Where `:time` and `:price` are the names of columns in my_data.
 
-### Args:
-* data_source: Data to be bound to aesthetics.
-* elements: Geometries, statistics, etc.
-* mapping: Aesthetics symbols (e.g. :x, :y, :color) mapped to names of columns in the data frame or other expressions.
+# Args:
+- data_source: Data to be bound to aesthetics.
+- elements: Geometries, statistics, etc.
+- mapping: Aesthetics symbols (e.g. :x, :y, :color) mapped to names of columns in the data frame or other expressions.
 """
 function plot(data_source::Union{AbstractArray, AbstractDataFrame},
               elements::ElementOrFunctionOrLayers...; mapping...)
@@ -304,39 +291,22 @@ function plot(elements::ElementOrFunctionOrLayers...; mapping...)
 end
 
 
-# The old fashioned (pre named arguments) version of plot.
-#
-# This version takes an explicit mapping dictionary, mapping aesthetics symbols
-# to expressions or columns in the data frame.
-#
-# Args:
-#   data_source: Data to be bound to aesthetics.
-#   mapping: Dictionary of aesthetics symbols (e.g. :x, :y, :color) to
-#            names of columns in the data frame or other expressions.
-#   elements: Geometries, statistics, etc.
-#
-# Returns:
-#   A Plot object.
-#
 """
-    plot(data_source::@compat(Union{(@compat Void), AbstractMatrix, AbstractDataFrame}),
-         mapping::Dict, elements::ElementOrFunctionOrLayers...)
+    plot(data_source::Union{Void, AbstractMatrix, AbstractDataFrame},
+         mapping::Dict, elements::ElementOrFunctionOrLayers...) -> Plot
 
 The old fashioned (pre named arguments) version of plot.
 
 This version takes an explicit mapping dictionary, mapping aesthetics symbols
 to expressions or columns in the data frame.
 
-### Args:
-* data_source: Data to be bound to aesthetics.
-* mapping: Dictionary of aesthetics symbols (e.g. :x, :y, :color) to
+# Args:
+- data_source: Data to be bound to aesthetics.
+- mapping: Dictionary of aesthetics symbols (e.g. :x, :y, :color) to
             names of columns in the data frame or other expressions.
-*   elements: Geometries, statistics, etc.
-
-### Returns:
-A Plot object.
+-   elements: Geometries, statistics, etc.
 """
-function plot(data_source::Union{(Void), AbstractArray, AbstractDataFrame},
+function plot(data_source::Union{Void, AbstractArray, AbstractDataFrame},
               mapping::Dict, elements::ElementOrFunctionOrLayers...)
     mapping = cleanmapping(mapping)
     p = Plot()
@@ -735,16 +705,9 @@ function render_prepare(plot::Plot)
 end
 
 """
-```
-render(plot::Plot)
-```
-Render a plot based on the Plot object
-
-### Args
-*   plot: Plot to be rendered.
+    render(plot::Plot) -> Context
 
-### Returns
-A Compose context containing the rendered plot.
+Render `plot` to a `Compose` context.
 """
 function render(plot::Plot)
     (plot, coord, plot_aes,
@@ -855,17 +818,14 @@ end
     draw(backend::Compose.Backend, p::Plot)
 
 A convenience version of Compose.draw without having to call render
-
-### Args
-* backend: The Compose.Backend object
-* p: The Plot object
 """
 draw(backend::Compose.Backend, p::Plot) = draw(backend, render(p))
 
 """
     title(ctx::Context, str::String, props::Property...) -> Context
 
-Add a title string to a group of plots, typically created with `vstack`, `hstack`, or `gridstack`.
+Add a title string to a group of plots, typically created with `vstack`,
+`hstack`, or `gridstack`.
 
 # Examples
 
@@ -884,7 +844,9 @@ title(ctx::Context, str::String, props::Compose.Property...) = vstack(
     vstack(ps::Union{Plot,Context}...)
     vstack(ps::Vector)
 
-Arrange plots into a vertical column.  Use `context()` as a placeholder for an empty panel.  Heterogeneous vectors must be typed.  See also `hstack`, `gridstack`, `subplot_grid`.
+Arrange plots into a vertical column.  Use `context()` as a placeholder for an
+empty panel.  Heterogeneous vectors must be typed.  See also `hstack`,
+`gridstack`, `subplot_grid`.
 
 # Examples
 
@@ -902,7 +864,9 @@ vstack(ps::Vector{Union{Plot,Context}}) = vstack(ps...)
     hstack(ps::Union{Plot,Context}...)
     hstack(ps::Vector)
 
-Arrange plots into a horizontal row.  Use `context()` as a placeholder for an empty panel.  Heterogeneous vectors must be typed.  See also `vstack`, `gridstack`, `subplot_grid`.
+Arrange plots into a horizontal row.  Use `context()` as a placeholder for an
+empty panel.  Heterogeneous vectors must be typed.  See also `vstack`,
+`gridstack`, `subplot_grid`.
 
 # Examples
 
@@ -919,7 +883,9 @@ hstack(ps::Vector{Union{Plot,Context}}) = hstack(ps...)
 """
     gridstack(ps::Matrix{Union{Plot,Context}})
 
-Arrange plots into a rectangular array.  Use `context()` as a placeholder for an empty panel.  Heterogeneous matrices must be typed.  See also `hstack`, `vstack`.
+Arrange plots into a rectangular array.  Use `context()` as a placeholder for
+an empty panel.  Heterogeneous matrices must be typed.  See also `hstack`,
+`vstack`.
 
 # Examples
 

src/geom/bar.jl

@@ -11,58 +11,39 @@ BarGeometry(; position=:stack, orientation=:vertical, tag=empty_tag) =
 
 """
 
-    Geom.bar[(; position, orientation)]
+    Geom.bar[(; position=:stack, orientation=:vertical)]
 
-Draw bar plots. This geometry works on pre-summarized data such as counts. To
-draw histograms from a series of observations, add [`Stat.histogram`](@ref) to the plot,
-or use the convenient geometry [`Geom.histogram`](@ref).
+Draw bars of height `y` centered at positions `x`, or from `xmin` to `xmax`.
+If orientation is `:horizontal` switch x for y.
 
-# Aesthetics
-- `y`: Height of each bar.
-- `color` (optional): Group categorically by color.
+Optionally categorically groups bars using the `color` aesthetic.  If
+`position` is `:stack` they will placed on top of each other;  if it is
+`:dodge` they will be placed side by side.
 
-Either
-
-- `x`: Position of each bar.
-
-Or
+To draw histograms from a series of observations, instead of counts, add
+[`Stat.histogram`](@ref) to the plot, or use the convenient geometry
+[`Geom.histogram`](@ref).
+"""
+const bar = BarGeometry
 
-- `xmin`: Starting x positions for each bar.
-- `xmax`: End x positions for each bar.
+"""
+    Geom.histogram[(; position=:stack, bincount=nothing,
+                    minbincount=3, maxbincount=150,
+                    orientation=:vertical, density=false)]
 
-If `x` is given, a bar will be drawn at each x value, specifying both `xmin` and
-`xmax` allows bars of variable width to be drawn.
+Plot histograms of the `x` aesthetic if `orientation` is `:vertical`, or the `y`
+aesthetic if it is `:horizontal`.  Optionally group by the `color` aesthetic,
+in which case the bars are arranged on top of each other if `position` is
+`:stack`, or placed side by side if it is `:dodge`.
 
-# Arguments
-- `position`: Either `:stack` or `:dodge`. If the `color` aesthetic is
-    bound this determines how bars of different colors should be arranged:
-    stacked on top of each other, or placed side by side.
+Alternatively, if `density` is true, plot a line showing continuous density
+rather than discrete bars of counts.
 
-- `orientation`: Either `:vertical` (default) or `:horizontal`. If
-    `:horizontal`, then the required aesthetics are `y` or `ymin/ymax`.
-"""
-const bar = BarGeometry
+`bincount` specifies the number of bins to use. If set to `nothing`, an
+optimization method is used to determine a reasonable value which uses
+`minbincount` and `maxbincount` to set the lower and upper limits.
 
-"""
-    Geom.histogram[(; position, orientation, bincount, minbincount, maxbincount, density)]
-
-Draw histograms. An alias for [`Geom.bar`](@ref) with [`Stat.histogram`](@ref).
-
-# Aesthetics
-- `x`: Sample to draw histogram from.
-- `color` (optional): Group categorically by color.
-
-# Arguments
-- `position`: Either `:stack` or `:dodge`. If the `color` aesthetic is
-    bound this determines how bars of different colors should be arranged:
-    stacked on top of each other, or placed side by side.
-- `orientation`: Either `:vertical` (default) or `:horizontal`. If
-    `:horizontal`, then the required aesthetic is `y` instead of `x`.
-- `bincount`: Number of bins to use. If unspecified, an optimization method
-    is used to determine a reasonable value.
-- `minbincount`: Set a lower limit when automatically choosing a bin count.
-- `maxbincount`: Set an upper limit when automatically choosing a bin count.
-- `density`: If true, use density rather that counts.
+An alias for [`Geom.bar`](@ref) with [`Stat.histogram`](@ref).
 """
 histogram(; position=:stack, bincount=nothing,
                    minbincount=3, maxbincount=150,

src/geom/beeswarm.jl

@@ -8,20 +8,12 @@ BeeswarmGeometry(; orientation=:vertical, padding=0.1mm, tag=empty_tag) =
         BeeswarmGeometry(orientation, padding, tag)
 
 """
-    Geom.beeswarm[; (orientation,padding)]
+    Geom.beeswarm[; (orientation=:vertical, padding=0.1mm)]
 
-Plot points, shifting them on the x- or y-axis to avoid overlaps.
-
-# Aesthetics
-- `x`: X-axis position.
-- `y`: Y-axis position.
-- `color` (optional): Point color (categorial or continuous).
-
-# Arguments
-- `orientation`: `:horizontal` or `:vertical`.  Points will be shifted on the
-    y-axis to avoid overlap if orientation in horizontal, and on the x-axis, if
-    vertical.
-- `padding`: Minimum distance between two points.
+Plot the `x` and `y` aesthetics, the former being categorical, by shifting the
+x position of each point to ensure that there is at least `padding` gap between
+neighbors.  If `orientation` is `:horizontal`, switch x for y.  Points
+can optionally be colored using the `color` aesthetic.
 """
 const beeswarm = BeeswarmGeometry