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/coordinates.md

@@ -6,6 +6,10 @@ Author = "Tamas Nagy"
 
 Coordinate systems are mappings between a coordinate space and the 2D rendered output.
 
+```@index
+Modules = [Coord]
+```
+
 ```@autodocs
 Modules = [Coord]
 ```

docs/src/lib/gadfly.md

@@ -4,6 +4,10 @@ Author = "Ben J. Arthur"
 
 # Gadfly
 
+```@index
+Modules = [Gadfly]
+```
+
 ```@autodocs
 Modules = [Gadfly]
 ```

docs/src/lib/geometries.md

@@ -5,11 +5,25 @@ Author = "Daniel C. Jones"
 # [Geometries](@id lib_geom)
 
 Geometries are responsible for actually doing the drawing. A geometry takes
-as input one or more aesthetics, and used data bound to these aesthetics to
+as input one or more aesthetics, and use data bound to these aesthetics to
 draw things. For instance, the [Geom.point](@ref) geometry draws points using
 the `x` and `y` aesthetics, while the [Geom.line](@ref) geometry draws lines
 with those same two aesthetics.
 
+Core geometries:
+
+```@index
+Modules = [Geom]
+Order = [:type]
+```
+
+Derived geometries:
+
+```@index
+Modules = [Geom]
+Order = [:function]
+```
+
 ```@autodocs
 Modules = [Geom]
 ```

docs/src/lib/guides.md

@@ -9,6 +9,10 @@ actual visualization, such as axis ticks and labels and color keys. The major
 distinction is that geometries always draw within the rectangular plot frame,
 while guides have some special layout considerations.
 
+```@index
+Modules = [Guide]
+```
+
 ```@autodocs
 Modules = [Guide]
 ```

docs/src/lib/scales.md

@@ -11,6 +11,10 @@ the original value. For example, the Scale.x_log10 aesthetic maps the
 but keeps track of the original value so that data points are properly
 identified.
 
+```@index
+Modules = [Scale]
+```
+
 ```@autodocs
 Modules = [Scale]
 ```

docs/src/lib/shapes.md

@@ -8,6 +8,10 @@ Shapes, when combined with [Geom.point](@ref), specify the appearance of
 markers.  Available shapes include circle, square, diamond, cross, xcross,
 utriangle, dtriangle, star1, star2, hexagon, octogon, hline, and vline.
 
+```@index
+Modules = [Shape]
+```
+
 ```@autodocs
 Modules = [Shape]
 ```

docs/src/lib/statistics.md

@@ -5,11 +5,15 @@ 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.
 
+```@index
+Modules = [Stat]
+```
+
 ```@autodocs
 Modules = [Stat]
 ```

src/Gadfly.jl

@@ -69,6 +69,14 @@ 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 +110,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 +120,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 +142,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 +250,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 +268,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 +290,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 +704,9 @@ function render_prepare(plot::Plot)
 end
 
 """
-```
-render(plot::Plot)
-```
-Render a plot based on the Plot object
+    render(plot::Plot) -> Context
 
-### Args
-*   plot: Plot to be rendered.
-
-### Returns
-A Compose context containing the rendered plot.
+Render `plot` to a `Compose` context.
 """
 function render(plot::Plot)
     (plot, coord, plot_aes,
@@ -855,17 +817,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 +843,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
 
@@ -893,6 +854,7 @@ p1 = plot(x=[1,2], y=[3,4], Geom.line);
 p2 = Compose.context();
 vstack(p1, p2)
 vstack(Union{Plot,Compose.Context}[p1, p2])
+```
 """
 vstack(ps::Union{Plot,Context}...) = vstack([typeof(p)==Plot ? render(p) : p for p in ps]...)
 vstack(ps::Vector{Plot}) = vstack(ps...)
@@ -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