Merge pull request #1012 from mkborregaard/more_docstrings

Specified some docstrings

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...)

src/animation.jl

@@ -1,4 +1,4 @@
-
+"Represents an animation object"
 immutable Animation
     dir::String
     frames::Vector{String}
@@ -9,6 +9,11 @@ function Animation()
     Animation(tmpdir, String[])
 end
 
+"""
+    frame(animation[, plot])
+
+Add a plot (the current plot if not specified) to an existing animation
+"""
 function frame{P<:AbstractPlot}(anim::Animation, plt::P=current())
     i = length(anim.frames) + 1
     filename = @sprintf("%06d.png", i)
@@ -81,7 +86,7 @@ function buildanimation(animdir::AbstractString, fn::AbstractString;
     catch err
         warn("""Tried to create gif using convert (ImageMagick), but got error: $err
             ImageMagick can be installed by executing `Pkg.add("ImageMagick")`.
-            You may also need to install the imagemagick c++ library through your operating system. 
+            You may also need to install the imagemagick c++ library through your operating system.
             Will try ffmpeg, but it's lower quality...)""")
 
         # low quality

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

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")
 

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)
 
@@ -32,6 +39,7 @@ vertices(shape::Shape) = collect(zip(shape.x, shape.y))
 #deprecated
 @deprecate shape_coords coords
 
+"return the vertex points from a Shape or Segments object"
 function coords(shape::Shape)
     shape.x, shape.y
 end
@@ -156,6 +164,7 @@ Shape(k::Symbol) = deepcopy(_shapes[k])
 
 
 # uses the centroid calculation from https://en.wikipedia.org/wiki/Centroid#Centroid_of_polygon
+"return the centroid of a Shape"
 function center(shape::Shape)
     x, y = coords(shape)
     n = length(x)
@@ -189,6 +198,7 @@ function scale(shape::Shape, x::Real, y::Real = x, c = center(shape))
     scale!(shapecopy, x, y, c)
 end
 
+"translate a Shape in space"
 function translate!(shape::Shape, x::Real, y::Real = x)
     sx, sy = coords(shape)
     for i=1:length(sx)
@@ -227,6 +237,7 @@ function rotate!(shape::Shape, Θ::Real, c = center(shape))
     shape
 end
 
+"rotate an object in space"
 function rotate(shape::Shape, Θ::Real, c = center(shape))
     shapecopy = deepcopy(shape)
     rotate!(shapecopy, Θ, c)
@@ -331,6 +342,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...)
@@ -350,6 +366,11 @@ immutable Stroke
   style
 end
 
+"""
+    stroke(args...; alpha = nothing)
+
+Define the properties of the stroke used in plotting lines
+"""
 function stroke(args...; alpha = nothing)
   width = 1
   color = :black
@@ -597,6 +618,12 @@ immutable Arrow
     headwidth::Float64
 end
 
+"""
+    arrow(args...)
+
+Define arrowheads to apply to lines - args are `style` (`:open` or `:closed`),
+`side` (`:head`, `:tail` or `:both`), `headlength` and `headwidth`
+"""
 function arrow(args...)
     style = :simple
     side = :head
@@ -652,7 +679,7 @@ immutable Formatted{T}
 end
 
 # -----------------------------------------------------------------------
-
+"create a BezierCurve for plotting"
 type BezierCurve{T <: FixedSizeArrays.Vec}
     control_points::Vector{T}
 end

src/examples.jl

@@ -360,6 +360,13 @@ function test_examples(pkgname::Symbol, idx::Int; debug = false, disp = true)
 end
 
 # generate all plots and create a dict mapping idx --> plt
+"""
+test_examples(pkgname[, idx]; debug = false, disp = true, sleep = nothing,
+                                        skip = [], only = nothing
+
+Run the `idx` test example for a given backend, or all examples if `idx`
+is not specified. 
+"""
 function test_examples(pkgname::Symbol; debug = false, disp = true, sleep = nothing,
                                         skip = [], only = nothing)
   Plots._debugMode.on = debug

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...;

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())
 
 

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")

src/plotattr.jl

@@ -14,6 +14,12 @@ function lookup_aliases(attrtype, attribute)
     error("There is no attribute named $attribute in $attrtype")
 end
 
+"""
+    plotattr([attr])
+
+Look up the properties of a Plots attribute, or specify an attribute type. Call `plotattr()` for options.
+The information is the same as that given on https://juliaplots.github.io/attributes/.
+"""
 function plotattr()
     println("Specify an attribute type to get a list of supported attributes. Options are $(attrtypes())")
 end

src/recipes.jl

@@ -847,6 +847,7 @@ end
 
 # TODO: move OHLC to PlotRecipes finance.jl
 
+"Represent Open High Low Close data (used in finance)"
 type OHLC{T<:Real}
   open::T
   high::T

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)
 

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

src/utils.jl

@@ -137,7 +137,7 @@ function imageHack(d::KW)
 end
 # ---------------------------------------------------------------
 
-
+"Build line segments for plotting"
 type Segments{T}
     pts::Vector{T}
 end
@@ -185,6 +185,7 @@ type SegmentsIterator
     args::Tuple
     n::Int
 end
+
 function iter_segments(args...)
     tup = Plots.wraptuple(args)
     n = maximum(map(length, tup))
@@ -500,9 +501,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 +556,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