add missing docstrings for all exported methods

Author: bjarthur

src/geom/errorbar.jl

@@ -32,12 +32,36 @@ The `x`, `ymin`, `ymax` and/or `y`, `xmin`, `xmax` aesthetics must be defined.
 With the later a vertical error bar is drawn, and the former, a horizontal bar.
 """
 const errorbar = ErrorBarGeometry
+
+"""
+    Geom.xerrorbar
+
+Draw vertical error bars.
+
+# Aesthetics
+- `y`: Y-position of the bar.
+- `xmin`: Left-most X-position
+- `xmax`: Right-most X-position.
+- `color` (optional): Bar color (categorial or continuous)
+"""
 const xerrorbar = XErrorBarGeometry
+
+"""
+    Geom.yerrorbar
+
+Draw horizontal error bars.
+
+# Aesthetics
+- `x`: X-position of the bar.
+- `ymin`: Lower Y-position.
+- `ymax`: Upper Y-position.
+- `color` (optional): Bar color (categorial or continuous)
+"""
 const yerrorbar = YErrorBarGeometry
 
 element_aesthetics(::ErrorBarGeometry) = [:x, :y, :xmin, :xmax, :ymin, :ymax]
-element_aesthetics(::YErrorBarGeometry) = [:x, :ymin, :ymax]
 element_aesthetics(::XErrorBarGeometry) = [:y, :xmin, :xmax]
+element_aesthetics(::YErrorBarGeometry) = [:x, :ymin, :ymax]
 
 # Generate a form for the errorbar geometry.
 #

src/geom/segment.jl

@@ -32,6 +32,9 @@ Draw separate line segments/vectors/arrows.
 const segment = SegmentGeometry
 
 # Leave this as a function, pending extra arguments e.g. arrow attributes
+"""
+    Geom.vector[(; filled::Bool=false)]
+"""
 vector(; filled::Bool=false) = SegmentGeometry(arrow=true, filled=filled)
 
 """

src/shapes.jl

@@ -5,6 +5,9 @@ module Shape
 using Measures
 using Compose: x_measure, y_measure, circle, rectangle, polygon, line
 
+"""
+    square(xs, ys, rs)
+"""
 function square(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
     n = max(length(xs), length(ys), length(rs))
 
@@ -25,6 +28,9 @@ function square(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
     return rectangle(rect_xs, rect_ys, rect_ws, rect_ws)
 end
 
+"""
+    diamond(xs, ys, rs)
+"""
 function diamond(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
     n = max(length(xs), length(ys), length(rs))
 
@@ -39,6 +45,9 @@ function diamond(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
     return polygon(polys)
 end
 
+"""
+    cross(xs, ys, rs)
+"""
 function cross(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
   n = max(length(xs), length(ys), length(rs))
   polys = Vector{Vector{Tuple{Measure, Measure}}}(n)
@@ -64,6 +73,9 @@ function cross(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
   return polygon(polys)
 end
 
+"""
+    xcross(xs, ys, rs)
+"""
 function xcross(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
   n = max(length(xs), length(ys), length(rs))
   polys = Vector{Vector{Tuple{Measure, Measure}}}(n)
@@ -84,6 +96,9 @@ function xcross(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
   return polygon(polys)
 end
 
+"""
+    utriangle(xs, ys, rs, scalar=1)
+"""
 function utriangle(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray, scalar = 1)
   n = max(length(xs), length(ys), length(rs))
   polys = Vector{Vector{Tuple{Measure, Measure}}}(n)
@@ -104,8 +119,14 @@ function utriangle(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray, scal
   return polygon(polys)
 end
 
+"""
+    dtriangle(xs, ys, rs)
+"""
 dtriangle(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray) = utriangle(xs, ys, rs, -1)
 
+"""
+    star1(xs, ys, rs, scalar=1)
+"""
 function star1(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray, scalar = 1)
   n = max(length(xs), length(ys), length(rs))
   polys = Vector{Vector{Tuple{Measure, Measure}}}(n)
@@ -130,6 +151,9 @@ function star1(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray, scalar =
   return polygon(polys)
 end
 
+"""
+    star2(xs, ys, rs, scalar=1)
+"""
 function star2(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray, scalar = 1)
   n = max(length(xs), length(ys), length(rs))
   polys = Vector{Vector{Tuple{Measure, Measure}}}(n)
@@ -149,6 +173,9 @@ function star2(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray, scalar =
   return polygon(polys)
 end
 
+"""
+    hexagon(xs, ys, rs)
+"""
 function hexagon(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
   n = max(length(xs), length(ys), length(rs))
 
@@ -170,6 +197,9 @@ function hexagon(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
   return polygon(polys)
 end
 
+"""
+    octagon(xs, ys, rs)
+"""
 function octagon(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
   n = max(length(xs), length(ys), length(rs))
 
@@ -191,6 +221,9 @@ function octagon(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
   return polygon(polys)
 end
 
+"""
+    hline(xs, ys, rs)
+"""
 function hline(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
     n = max(length(xs), length(ys), length(rs))
 
@@ -206,6 +239,9 @@ function hline(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
     return line(line_ps)
 end
 
+"""
+    vline(xs, ys, rs)
+"""
 function vline(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)
     n = max(length(xs), length(ys), length(rs))
 

src/statistics.jl

@@ -55,6 +55,9 @@ end
 
 struct Nil <: Gadfly.StatisticElement end
 
+"""
+    Stat.Nil
+"""
 const nil = Nil
 
 struct Identity <: Gadfly.StatisticElement end
@@ -104,11 +107,17 @@ end
 
 struct RectbinStatistic <: Gadfly.StatisticElement end
 
-const rectbin = RectbinStatistic
-
 input_aesthetics(stat::RectbinStatistic) = [:x, :y]
 output_aesthetics(stat::RectbinStatistic) = [:xmin, :xmax, :ymin, :ymax]
 
+"""
+    Stat.rectbin
+
+Transform $(aes2str(input_aesthetics(rectbin()))) into
+$(aes2str(output_aesthetics(rectbin()))).
+"""
+const rectbin = RectbinStatistic
+
 function apply_statistic(stat::RectbinStatistic,
                          scales::Dict{Symbol, Gadfly.ScaleElement},
                          coord::Gadfly.CoordinateElement,
@@ -148,6 +157,12 @@ output_aesthetics(stat::BarStatistic) =
 default_scales(stat::BarStatistic) = stat.orientation == :vertical ?
         [Gadfly.Scale.y_continuous()] : [Gadfly.Scale.x_continuous()]
 
+"""
+    Stat.bar[(; position=:stack, orientation=:vertical)]
+
+Transform $(aes2str(input_aesthetics(bar()))) into
+$(aes2str(output_aesthetics(bar()))).
+"""
 const bar = BarStatistic
 
 function apply_statistic(stat::BarStatistic,
@@ -1409,13 +1424,19 @@ struct FunctionStatistic <: Gadfly.StatisticElement
 end
 FunctionStatistic(; num_samples=250) = FunctionStatistic(num_samples)
 
+input_aesthetics(::FunctionStatistic) = [:y, :xmin, :xmax]
+output_aesthetics(::FunctionStatistic) = [:x, :y, :group]
+
+"""
+    Stat.func[(; num_samples=250)]
+
+Transform $(aes2str(input_aesthetics(func()))) into
+$(aes2str(output_aesthetics(func()))).
+"""
 const func = FunctionStatistic
 
 default_scales(::FunctionStatistic) = [Gadfly.Scale.x_continuous(), Gadfly.Scale.y_continuous()]
 
-input_aesthetics(::FunctionStatistic) = [:y, :xmin, :xmax]
-output_aesthetics(::FunctionStatistic) = [:x, :y, :group]
-
 function apply_statistic(stat::FunctionStatistic,
                          scales::Dict{Symbol, Gadfly.ScaleElement},
                          coord::Gadfly.CoordinateElement,
@@ -1475,6 +1496,12 @@ ContourStatistic(; levels=15, samples=150) = ContourStatistic(levels, samples)
 input_aesthetics(::ContourStatistic) = [:z, :xmin, :xmax, :ymin, :ymax]
 output_aesthetics(::ContourStatistic) = [:x, :y, :color, :group]
 
+"""
+    Stat.contour[(; levels=15, samples=150)]
+
+Transform $(aes2str(input_aesthetics(contour()))) into
+$(aes2str(output_aesthetics(contour()))).
+"""
 const contour = ContourStatistic
 
 default_scales(::ContourStatistic, t::Gadfly.Theme=Gadfly.current_theme()) =
@@ -1858,7 +1885,20 @@ function default_scales(stat::EnumerateStatistic)
     end
 end
 
+"""
+    Stat.x_enumerate
+
+Transform $(aes2str(input_aesthetics(x_enumerate))) into
+$(aes2str(output_aesthetics(x_enumerate))).
+"""
 const x_enumerate = EnumerateStatistic(:x)
+
+"""
+    Stat.y_enumerate
+
+Transform $(aes2str(input_aesthetics(y_enumerate))) into
+$(aes2str(output_aesthetics(y_enumerate))).
+"""
 const y_enumerate = EnumerateStatistic(:y)
 
 function apply_statistic(stat::EnumerateStatistic,
@@ -1891,6 +1931,12 @@ default_scales(stat::VecFieldStatistic, t::Gadfly.Theme=Gadfly.current_theme())
         [Gadfly.Scale.z_func(), Gadfly.Scale.x_continuous(), Gadfly.Scale.y_continuous(),
             t.continuous_color_scale ]
 
+"""
+    Stat.vectorfield[(; smoothness=1.0, scale=1.0, samples=20)]
+
+Transform $(aes2str(input_aesthetics(vectorfield()))) into
+$(aes2str(output_aesthetics(vectorfield()))).
+"""
 const vectorfield = VecFieldStatistic
 
 function apply_statistic(stat::VecFieldStatistic,
@@ -1957,6 +2003,12 @@ output_aesthetics(stat::HairStatistic) = [:x, :y, :xend, :yend]
 
 default_scales(stat::HairStatistic) = [Gadfly.Scale.x_continuous(), Gadfly.Scale.y_continuous()]
 
+"""
+    Stat.hair[(;intercept=0.0, orientation=:vertical)]
+
+Transform $(aes2str(input_aesthetics(hair()))) into
+$(aes2str(output_aesthetics(hair()))).
+"""
 const hair = HairStatistic
 
 function apply_statistic(stat::HairStatistic,
@@ -1987,10 +2039,16 @@ function EllipseStatistic(;
     return EllipseStatistic(distribution, levels, nsegments)
 end
 
-Gadfly.input_aesthetics(stat::EllipseStatistic) = [:x, :y]
-Gadfly.output_aesthetics(stat::EllipseStatistic) = [:x, :y]
-Gadfly.default_scales(stat::EllipseStatistic) = [Gadfly.Scale.x_continuous(), Gadfly.Scale.y_continuous()]
+input_aesthetics(stat::EllipseStatistic) = [:x, :y]
+output_aesthetics(stat::EllipseStatistic) = [:x, :y]
+default_scales(stat::EllipseStatistic) = [Gadfly.Scale.x_continuous(), Gadfly.Scale.y_continuous()]
 
+"""
+    Stat.ellipse[(; distribution=MvNormal, levels=[0.95], nsegments=51)]
+
+Transform $(aes2str(input_aesthetics(ellipse()))) into
+$(aes2str(output_aesthetics(ellipse()))).
+"""
 const ellipse = EllipseStatistic
 
 function Gadfly.Stat.apply_statistic(stat::EllipseStatistic,