From 66ce38d94851eb83622be9975c5af426dd0e57ae Mon Sep 17 00:00:00 2001
From: "Michael K. Borregaard" <mkborregaard@snm.ku.dk>
Date: Tue, 15 Aug 2017 23:02:31 +0200
Subject: [PATCH] Specified some docstrings

---
 src/Plots.jl      | 32 +++++++++++++++++++++++++++++++-
 src/args.jl       |  1 -
 src/backends.jl   |  3 +++
 src/components.jl | 12 ++++++++++++
 src/layouts.jl    | 12 ++++++++++++
 src/output.jl     | 12 ++++++++++++
 src/plot.jl       |  4 ++++
 src/subplots.jl   |  5 +++++
 src/themes.jl     |  4 ++++
 src/utils.jl      | 21 ++++++++++++++++++++-
 10 files changed, 103 insertions(+), 3 deletions(-)

diff --git a/src/Plots.jl b/src/Plots.jl
index bca0d9c9..c75a8e65 100644
--- a/src/Plots.jl
+++ b/src/Plots.jl
@@ -188,32 +188,62 @@ include("output.jl")
 @shorthands quiver
 @shorthands curves
 
+"Plot a pie diagram"
 pie(args...; kw...)        = plot(args...; kw...,  seriestype = :pie, aspect_ratio = :equal, grid=false, xticks=nothing, yticks=nothing)
 pie!(args...; kw...)       = plot!(args...; kw..., seriestype = :pie, aspect_ratio = :equal, grid=false, xticks=nothing, yticks=nothing)
+
+"Plot with seriestype :path3d"
 plot3d(args...; kw...)     = plot(args...; kw...,  seriestype = :path3d)
 plot3d!(args...; kw...)    = plot!(args...; kw..., seriestype = :path3d)
 
-
+"Add title to an existing plot"
 title!(s::AbstractString; kw...)                 = plot!(; title = s, kw...)
+
+"Add xlabel to an existing plot"
 xlabel!(s::AbstractString; kw...)                = plot!(; xlabel = s, kw...)
+
+"Add ylabel to an existing plot"
 ylabel!(s::AbstractString; kw...)                = plot!(; ylabel = s, kw...)
+
+"Set xlims for an existing plot"
 xlims!{T<:Real,S<:Real}(lims::Tuple{T,S}; kw...) = plot!(; xlims = lims, kw...)
+
+"Set ylims for an existing plot"
 ylims!{T<:Real,S<:Real}(lims::Tuple{T,S}; kw...) = plot!(; ylims = lims, kw...)
+
+"Set zlims for an existing plot"
 zlims!{T<:Real,S<:Real}(lims::Tuple{T,S}; kw...) = plot!(; zlims = lims, kw...)
+
 xlims!(xmin::Real, xmax::Real; kw...)                     = plot!(; xlims = (xmin,xmax), kw...)
 ylims!(ymin::Real, ymax::Real; kw...)                     = plot!(; ylims = (ymin,ymax), kw...)
 zlims!(zmin::Real, zmax::Real; kw...)                     = plot!(; zlims = (zmin,zmax), kw...)
+
+
+"Set xticks for an existing plot"
 xticks!{T<:Real}(v::AVec{T}; kw...)                       = plot!(; xticks = v, kw...)
+
+"Set yticks for an existing plot"
 yticks!{T<:Real}(v::AVec{T}; kw...)                       = plot!(; yticks = v, kw...)
+
 xticks!{T<:Real,S<:AbstractString}(
               ticks::AVec{T}, labels::AVec{S}; kw...)     = plot!(; xticks = (ticks,labels), kw...)
 yticks!{T<:Real,S<:AbstractString}(
               ticks::AVec{T}, labels::AVec{S}; kw...)     = plot!(; yticks = (ticks,labels), kw...)
+
+"Add annotations to an existing plot"
 annotate!(anns...; kw...)                                 = plot!(; annotation = anns, kw...)
 annotate!{T<:Tuple}(anns::AVec{T}; kw...)                 = plot!(; annotation = anns, kw...)
+
+"Flip the current plots' x axis"
 xflip!(flip::Bool = true; kw...)                          = plot!(; xflip = flip, kw...)
+
+"Flip the current plots' y axis"
 yflip!(flip::Bool = true; kw...)                          = plot!(; yflip = flip, kw...)
+
+"Specify x axis attributes for an existing plot"
 xaxis!(args...; kw...)                                    = plot!(; xaxis = args, kw...)
+
+"Specify x axis attributes for an existing plot"
 yaxis!(args...; kw...)                                    = plot!(; yaxis = args, kw...)
 xgrid!(args...; kw...)                                    = plot!(; xgrid = args, kw...)
 ygrid!(args...; kw...)                                    = plot!(; ygrid = args, kw...)
diff --git a/src/args.jl b/src/args.jl
index d861fea3..37dd250e 100644
--- a/src/args.jl
+++ b/src/args.jl
@@ -512,7 +512,6 @@ end
 `default(; kw...)` will set the current default value for each key/value pair
 `default(d, key)` returns the key from d if it exists, otherwise `default(key)`
 """
-
 function default(k::Symbol)
     k = get(_keyAliases, k, k)
     for defaults in _all_defaults
diff --git a/src/backends.jl b/src/backends.jl
index 19a9c6ea..b445807c 100644
--- a/src/backends.jl
+++ b/src/backends.jl
@@ -6,7 +6,10 @@ const _backendSymbol = Dict{DataType, Symbol}(NoBackend => :none)
 const _backends = Symbol[]
 const _initialized_backends = Set{Symbol}()
 
+"Returns a list of supported backends"
 backends() = _backends
+
+"Returns the name of the current backend"
 backend_name() = CURRENT_BACKEND.sym
 _backend_instance(sym::Symbol) = haskey(_backendType, sym) ? _backendType[sym]() : error("Unsupported backend $sym")
 
diff --git a/src/components.jl b/src/components.jl
index 2962f184..0ffe6226 100644
--- a/src/components.jl
+++ b/src/components.jl
@@ -22,6 +22,13 @@ immutable Shape
     #     end
     # end
 end
+
+"""
+    Shape(x, y)
+    Shape(vertices)
+
+Construct a polygon to be plotted
+"""
 Shape(verts::AVec) = Shape(unzip(verts)...)
 Shape(s::Shape) = deepcopy(s)
 
@@ -331,6 +338,11 @@ immutable PlotText
 end
 PlotText(str) = PlotText(string(str), font())
 
+"""
+    text(string, args...)
+
+Create a PlotText object wrapping a string with font info, for plot annotations
+"""
 text(t::PlotText) = t
 text(str::AbstractString, f::Font) = PlotText(str, f)
 function text(str, args...)
diff --git a/src/layouts.jl b/src/layouts.jl
index 71f8b7a1..9e90a2f1 100644
--- a/src/layouts.jl
+++ b/src/layouts.jl
@@ -133,7 +133,12 @@ make_measure_hor(m::Measure) = m
 make_measure_vert(n::Number) = n * h
 make_measure_vert(m::Measure) = m
 
+"""
+    bbox(x, y, w, h [,originargs...])
+    bbox(layout)
 
+Create a bounding box for plotting
+"""
 function bbox(x, y, w, h, oarg1::Symbol, originargs::Symbol...)
     oargs = vcat(oarg1, originargs...)
     orighor = :left
@@ -253,6 +258,13 @@ type GridLayout <: AbstractLayout
     attr::KW
 end
 
+"""
+    grid(args...; kw...)
+
+Create a grid layout for subplots. `args` specify the dimensions, e.g.
+`grid(3,2, widths = (0.6,04))` creates a grid with three rows and two
+columns of different width.
+"""
 grid(args...; kw...) = GridLayout(args...; kw...)
 
 function GridLayout(dims...;
diff --git a/src/output.jl b/src/output.jl
index 5c036fe7..14f15c30 100644
--- a/src/output.jl
+++ b/src/output.jl
@@ -97,6 +97,13 @@ function addExtension(fn::AbstractString, ext::AbstractString)
   end
 end
 
+"""
+    savefig([plot,] filename)
+
+Save a Plot (the current plot if `plot` is not passed) to file. The file
+type is inferred from the file extension. All backends support png and pdf
+file types, some also support svg, ps, eps, html and tex.
+"""
 function savefig(plt::Plot, fn::AbstractString)
 
   # get the extension
@@ -119,7 +126,11 @@ savefig(fn::AbstractString) = savefig(current(), fn)
 
 
 # ---------------------------------------------------------
+"""
+    gui([plot])
 
+Display a plot using the backends' gui window
+"""
 gui(plt::Plot = current()) = display(PlotsDisplay(), plt)
 
 # IJulia only... inline display
@@ -198,6 +209,7 @@ for mime in keys(_mimeformats)
     end
 end
 
+"Close all open gui windows of the current backend"
 closeall() = closeall(backend())
 
 
diff --git a/src/plot.jl b/src/plot.jl
index 3ab41701..3e6dd9a3 100644
--- a/src/plot.jl
+++ b/src/plot.jl
@@ -6,6 +6,10 @@ const CURRENT_PLOT = CurrentPlot(Nullable{AbstractPlot}())
 
 isplotnull() = isnull(CURRENT_PLOT.nullableplot)
 
+"""
+    current()
+Returns the Plot object for the current plot
+"""
 function current()
     if isplotnull()
         error("No current plot/subplot")
diff --git a/src/subplots.jl b/src/subplots.jl
index ccd1478c..5629125f 100644
--- a/src/subplots.jl
+++ b/src/subplots.jl
@@ -13,6 +13,11 @@ function Subplot{T<:AbstractBackend}(::T; parent = RootLayout())
     )
 end
 
+"""
+    plotarea(subplot)
+
+Return the bounding box of a subplot
+"""
 plotarea(sp::Subplot) = sp.plotarea
 plotarea!(sp::Subplot, bbox::BoundingBox) = (sp.plotarea = bbox)
 
diff --git a/src/themes.jl b/src/themes.jl
index e7a39d02..840078dd 100644
--- a/src/themes.jl
+++ b/src/themes.jl
@@ -1,4 +1,8 @@
+"""
+    theme(s::Symbol)
 
+Specify the colour theme for plots.
+"""
 function theme(s::Symbol; kw...)
     # reset?
     if s == :none || s == :default
diff --git a/src/utils.jl b/src/utils.jl
index d8aced3d..6add802a 100644
--- a/src/utils.jl
+++ b/src/utils.jl
@@ -500,9 +500,28 @@ end
 function get_sp_lims(sp::Subplot, letter::Symbol)
     axis_limits(sp[Symbol(letter, :axis)])
 end
+
+"""
+    xlims([plt])
+
+Returns the x axis limits of the current plot or subplot
+"""
 xlims(sp::Subplot) = get_sp_lims(sp, :x)
+
+"""
+    ylims([plt])
+
+Returns the y axis limits of the current plot or subplot
+"""
 ylims(sp::Subplot) = get_sp_lims(sp, :y)
+
+"""
+    zlims([plt])
+
+Returns the z axis limits of the current plot or subplot
+"""
 zlims(sp::Subplot) = get_sp_lims(sp, :z)
+
 xlims(plt::Plot, sp_idx::Int = 1) = xlims(plt[sp_idx])
 ylims(plt::Plot, sp_idx::Int = 1) = ylims(plt[sp_idx])
 zlims(plt::Plot, sp_idx::Int = 1) = zlims(plt[sp_idx])
@@ -536,7 +555,7 @@ allFunctions(arg)   = trueOrAllTrue(a -> isa(a, Function), arg)
 """
 Allows temporary setting of backend and defaults for Plots. Settings apply only for the `do` block.  Example:
 ```
-with(:gadfly, size=(400,400), type=:histogram) do
+with(:gr, size=(400,400), type=:histogram) do
   plot(rand(10))
   plot(rand(10))
 end