rephrase docstrings to remove explicit Arguments section

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