small updates (#402)

Author: t-bltg

ext/FreeTypeExt.jl

@@ -1,5 +1,5 @@
 # adapted from github.com/JuliaGraphics/FreeTypeAbstraction.jl/blob/master/src/rendering.jl
-# credits to the `FreeTypeAbstraction` authors
+# credits to the `FreeTypeAbstraction` authors (@SimonDanisch, @jkrumbiegel).
 
 module FreeTypeExt
 
@@ -24,7 +24,7 @@ end
 
 mutable struct FTFont
     ft_ptr::FT_Face
-    lock::ReentrantLock # lock this for the duration of any FT operation on ft_ptr
+    lock::ReentrantLock  # lock this for the duration of any FT operation on ft_ptr
     function FTFont(ft_ptr::FT_Face)
         face = new(ft_ptr, ReentrantLock())
         finalizer(safe_free, face)
@@ -45,7 +45,7 @@ family_name(font::FTFont) = lowercase(ft_property(font, :family_name))
 style_name(font::FTFont) = lowercase(ft_property(font, :style_name))
 Base.propertynames(font::FTFont) = fieldnames(FT_FaceRec)
 
-# C interop
+# c interoperability
 Base.cconvert(::Type{FT_Face}, font::FTFont) = font
 Base.unsafe_convert(::Type{FT_Face}, font::FTFont) = font.ft_ptr
 
@@ -79,7 +79,7 @@ add_mono(fts...) = tuple(map(x -> x * "Mono", fts)..., fts...)
 fallback_fonts() =
 # those fallback fonts are likely to fail braille characters
     if Sys.islinux()
-        add_mono("DejaVu Sans ", "Ubuntu ", "Noto ", "Free", "Liberation ")
+        add_mono("DejaVu Sans ", "Ubuntu ", "Noto ", "Free", "Liberation ")  # NOTE: trailing space intended
     elseif Sys.isbsd()
         ("Courier New", "Helvetica")
     elseif Sys.iswindows()
@@ -274,16 +274,16 @@ one_or_typemax(::Type{T}) where {T<:Union{Real,Colorant}} =
 Render `str` into `img` using the font `face` of size `pixelsize` at coordinates `y0,x0`.
 Uses the conventions of freetype.org/freetype2/docs/glyphs/glyphs-3.html
 # Arguments
-* `y0,x0`: origin is in upper left with positive `y` going down
-* `fcolor`: foreground color; AbstractVector{T}, typemax(T) for T<:Integer, otherwise one(T)
-* `gcolor`: background color; AbstractVector{T}, typemax(T) for T<:Integer, otherwise one(T)
-* `bcolor`: canvas background color; set to `nothing` for transparent
-* `halign`: :hleft, :hcenter, or :hright
-* `valign`: :vtop, :vcenter, :vbaseline, or :vbttom
-* `bbox_glyph`: glyph bounding box color (debugging)
-* `bbox`: bounding box color (debugging)
-* `gstr`: background string or array of chars (for background sizing)
-* `incx`: extra x spacing
+- `y0,x0`: origin is in upper left with positive `y` going down.
+- `fcolor`: foreground color; AbstractVector{T}, typemax(T) for T<:Integer, otherwise one(T).
+- `gcolor`: background color; AbstractVector{T}, typemax(T) for T<:Integer, otherwise one(T).
+- `bcolor`: canvas background color; set to `nothing` for transparent.
+- `halign`: :hleft, :hcenter, or :hright.
+- `valign`: :vtop, :vcenter, :vbaseline, or :vbttom.
+- `bbox_glyph`: glyph bounding box color (debugging).
+- `bbox`: bounding box color (debugging).
+- `gstr`: background string or array of chars (for background sizing).
+- `incx`: extra x spacing.
 """
 function UnicodePlots.render_string!(
     img::AbstractMatrix{T},
@@ -455,7 +455,7 @@ add_recursive(result, path) =
 function __init__()
     ft_init()
     atexit(ft_done)
-    # This method of finding fonts might not work for exotic platforms,
+    # this method of finding fonts might not work for exotic platforms,
     # so we supply a way to help it with an environment variable.
     font_paths = if Sys.isapple()  # COV_EXCL_LINE
         [

src/canvas/asciicanvas.jl

@@ -1,10 +1,10 @@
 """
-As the name suggests the `AsciiCanvas` only uses ASCII characters to draw it's content.
+As the name suggests the `AsciiCanvas` only uses ASCII characters to draw its content.
 Naturally, it doesn't look quite as nice as the Unicode-based ones.
 However, in some situations it might yield better results.
 Printing plots to a file is one of those situations.
 
-The AsciiCanvas is best utilized in combination with `lineplot`.
+The AsciiCanvas is best used in combination with `lineplot`.
 For `scatterplot` we suggest to use the `DotCanvas` instead.
 """
 struct AsciiCanvas{YS<:Function,XS<:Function} <: LookupCanvas

src/canvas/blockcanvas.jl

@@ -2,7 +2,7 @@
 The `BlockCanvas` is also Unicode-based.
 It has half the resolution of the `BrailleCanvas`.
 In contrast to BrailleCanvas, the pixels don't have visible spacing between them.
-This canvas effectively turns every character into 4 pixels that can individually be manipulated using binary operations.
+This canvas effectively turns every character into four pixels that can individually be manipulated using binary operations.
 """
 struct BlockCanvas{YS<:Function,XS<:Function} <: LookupCanvas
     grid::Transpose{UInt16,Matrix{UInt16}}

src/canvas/braillecanvas.jl

@@ -1,4 +1,4 @@
-# braille dots composing ⣿
+# braille dots composing the character '⣿'
 const BRAILLE_SIGNS = UnicodeType.([
     '⠁' '⠈'
     '⠂' '⠐'
@@ -9,7 +9,7 @@ const BRAILLE_SIGNS = UnicodeType.([
 """
 The type of canvas with the highest resolution for Unicode-based plotting.
 It uses the Unicode characters for the Braille symbols to represent individual pixel.
-This effectively turns every character into 8 pixels that can individually be manipulated using binary operations.
+This effectively turns every character into eight pixels that can individually be manipulated using binary operations.
 """
 struct BrailleCanvas{YS<:Function,XS<:Function} <: Canvas
     grid::Transpose{UnicodeType,Matrix{UnicodeType}}

src/canvas/densitycanvas.jl

@@ -1,7 +1,7 @@
 const DEN_SIGNS = Ref((' ', '░', '▒', '▓', '█'))
 
 """
-Unlike the `BrailleCanvas`, the density canvas does not simply mark a "pixel" as set.
+Unlike the `BrailleCanvas`, the density canvas does not simply mark a pixel as set.
 Instead it increments a counter per character that keeps track of the frequency of pixels drawn in that character.
 Together with a variable that keeps track of the maximum frequency, the canvas can thus draw the density of datapoints.
 """

src/canvas/dotcanvas.jl

@@ -1,10 +1,10 @@
 """
-Similar to the `AsciiCanvas`, the `DotCanvas` only uses ASCII characters to draw it's content.
+Similar to the `AsciiCanvas`, the `DotCanvas` only uses ASCII characters to draw its content.
 Naturally, it doesn't look quite as nice as the Unicode-based ones.
 However, in some situations it might yield better results.
 Printing plots to a file is one of those situations.
 
-The DotCanvas is best utilized in combination with `scatterplot`.
+The DotCanvas is best used in combination with `scatterplot`.
 For `lineplot` we suggest to use the `AsciiCanvas` instead.
 """
 struct DotCanvas{YS<:Function,XS<:Function} <: LookupCanvas

src/canvas/lookupcanvas.jl

@@ -1,3 +1,6 @@
+"""
+Supertype for Look-Up Table (LUT) encoded canvases.
+"""
 abstract type LookupCanvas <: Canvas end
 
 function CreateLookupCanvas(

src/description.jl

@@ -164,7 +164,7 @@ Adds default keywords to a function signature, in a docstring.
 
 # Arguments
 
-- `extra::NamedTuple`: add extra keywords in the form `keyword=value`.
+- `extra::NamedTuple`: add extra keywords in the form `keyword = value`.
 - `default::Tuple`: default `UnicodePlots` keywords.
 - `add::Tuple`: add extra symbols, not listed in `default` but present in `KEYWORDS`.
 - `remove::Tuple`: remove symbols from `default`.
@@ -190,7 +190,7 @@ Defines arguments for docstring genreration.
 
 # Arguments
 
-- `desc::NamedTuple`: add argument description in the form `arg=desc`.
+- `desc::NamedTuple`: add argument description in the form `arg = desc`.
 - `default::Tuple`: default `UnicodePlots` keywords.
 - `add::Tuple`: add extra symbols, not listed in `default` but present in `DESCRIPTION`.
 - `remove::Tuple`: remove symbols from `default`.

src/graphics/imagegraphics.jl

@@ -24,7 +24,7 @@ end
 @inline nrows(c::ImageGraphics) = first(c.encoded_size)
 @inline ncols(c::ImageGraphics) = last(c.encoded_size)
 
-# # generic functions for  `ImageInTerminalExt`
+# # generic functions for `ImageInTerminalExt`
 function terminal_specs end
 function sixel_encode end
 function imshow end

src/interface/barplot.jl

@@ -26,7 +26,7 @@ $(arguments(
         dict = "a dictionary in which the keys will be used as `text` and the values will be used as `heights`",
         xscale = "`Function` or `Symbol` to transform the bar length before plotting: this effectively scales the `x`-axis without influencing the captions of the individual bars (use `xscale = :log10` for logscale)",
         color = "`Vector` of colors, or scalar - $(DESCRIPTION[:color])",
-        maximum = "optional maximal height"
+        maximum = "optional maximal height",
     ); remove = (:xlim, :ylim, :yscale, :height, :grid), add = (:symbols,),
 ))
 

src/interface/heatmap.jl

@@ -20,7 +20,7 @@ $(arguments(
         xfact = "scale for the `x` coordinate (defaults to 0 - i.e. each column in `A` maps to one unit, `x` origin starting at 1). If set to anything else, the x origin will start at 0",
         yoffset = "plotting offset for the `y` coordinate (after scaling)",
         xoffset = "plotting offset for the `x` coordinate (after scaling)",
-        array = "use array display convention (origin at the North-West corner of the plot, hence flipping `y` versus regular plots)"
+        array = "use array display convention (origin at the North-West corner of the plot, hence flipping `y` versus regular plots)",
     ); add = (Z_DESCRIPTION..., :fix_ar)
 ))
 
@@ -160,7 +160,7 @@ function heatmap(
         # for small plots, don't show colorbar by default
         get(pkw, :colorbar, false)
     else
-        # show colorbar by default, unless set to false, or labels == false
+        # show colorbar by default, unless set to false, or `labels = false`
         get(pkw, :colorbar, labels)
     end
 

src/interface/imageplot.jl

@@ -1,7 +1,7 @@
 """
     imageplot(img; kw...)
 
-Plot an image using `ImageInTerminal` (`sixel`s are supported if the terminal emulator supports it).
+Plot an image using `ImageInTerminal` (`sixel`s are supported if the terminal emulator supports them).
 
 # Usage
 

src/interface/scatterplot.jl

@@ -10,7 +10,7 @@ Draws the given points on a new canvas.
 
 The first (optional) vector `x` should contain the horizontal positions for all the points.
 The second vector `y` should then contain the corresponding vertical positions respectively.
-This means that the two vectors must be of the same length and ordering.
+This means that the two vectors must be of same length and ordering.
 
 # Usage
 

src/interface/stairs.jl

@@ -8,7 +8,7 @@ Draws a staircase plot on a new canvas.
 
 The first (optional) vector `x` should contain the horizontal positions for all the points.
 The second vector `y` should then contain the corresponding vertical positions respectively.
-This means that the two vectors must be of the same length and ordering.
+This means that the two vectors must be of same length and ordering.
 
 # Usage
 

src/interface/surfaceplot.jl

@@ -110,7 +110,7 @@ end
     Y::AbstractVecOrMat,
     Z::AbstractVecOrMat,
     H::Union{AbstractVecOrMat,Nothing} = nothing;
-    color::UserColorType = nothing,  # NOTE: nothing as default (uses colormap), but allow single color
+    color::UserColorType = nothing,  # NOTE: `nothing` as default (uses a colormap), but allow a single color
     colormap = KEYWORDS.colormap,
     lines::Bool = false,
     zlim = KEYWORDS.zlim,

src/show.jl

@@ -144,6 +144,9 @@ end
 
 Base.show(io::IO, p::Plot) = _show(io, print, print_color, p)
 
+"""
+Display a `Plot` object to a terminal emulator.
+"""
 function _show(end_io::IO, print_nocol, print_color, p::Plot)
     buf = PipeBuffer()  # buffering, for performance
     io_color = get(end_io, :color, false)
@@ -406,7 +409,7 @@ function save_image end
 """
     png_image(p::Plot, font = nothing, pixelsize = 32, transparent = true, foreground = nothing, background = nothing, bounding_box = nothing, bounding_box_glyph = nothing)
 
-Render `png` image.
+Renders a `png` image.
 
 # Arguments
 - `pixelsize::Integer = 32`: controls the image size scaling.

src/volume.jl

@@ -72,7 +72,7 @@ Computes the perspective projection matrix (see songho.ca/opengl/gl_projectionma
 # Arguments
 
     - `l`: left coordinate of the vertical clipping plane.
-    - `r` : right coordinate of the vertical clipping plane.
+    - `r`: right coordinate of the vertical clipping plane.
     - `b`: bottom coordinate of the horizontal clipping plane.
     - `t`: top coordinate of the horizontal clipping plane.
     - `n`: distance to the near depth clipping plane.
@@ -112,7 +112,7 @@ Computes the orthographic projection matrix (see songho.ca/opengl/gl_projectionm
 # Arguments
 
     - `l`: left coordinate of the vertical clipping plane.
-    - `r` : right coordinate of the vertical clipping plane.
+    - `r`: right coordinate of the vertical clipping plane.
     - `b`: bottom coordinate of the horizontal clipping plane.
     - `t`: top coordinate of the horizontal clipping plane.
     - `n`: distance to the near depth clipping plane.
@@ -138,7 +138,7 @@ ortho(l, r, b, t, n, f) = *(
 
 # Description
 
-Computes data center, minimum and maximum points, and cube diagonal.
+Computes data center, minimum and maximum points, and cube diagonal length.
 """
 function ctr_len_diag(x, y, z)
     mx, Mx = nanless_extrema(x)
@@ -238,7 +238,7 @@ struct MVP{E,T}
         is_ortho = projection ∈ (:ortho, :orthographic)
         ctr, mini, maxi, len, diag = ctr_len_diag(x, y, z)
 
-        # half the diagonal (cam distance to the center)
+        # half the diagonal (camera distance to the center)
         disto = dist = (diag / 2) / zoom
         distp = disto / 2
 
@@ -362,7 +362,7 @@ axis_line(tr, proj, start::AbstractVector{T}, stop::AbstractVector{T}) where {T}
 # Description
 
 Draws (X, Y, Z) cartesian coordinates axes in (R, G, B) colors, at position `p = (x, y, z)`.
-If `p = (x, y)` is given, draws at screen coordinates.
+If `p = (x, y)` is given, draws at screen coordinates instead.
 """
 function draw_axes!(plot, x::T, y::T, z::T, scale = T(0.25)) where {T<:AbstractFloat}
     tr = plot.projection
@@ -388,6 +388,7 @@ function draw_axes!(plot, x::T, y::T, z::T, scale = T(0.25)) where {T<:AbstractF
 
     plot
 end
+
 draw_axes!(plot, x::T, y::T, z::Nothing, args...) where {T<:AbstractFloat} =
     let (x, y, z) = transform_matrix(plot.projection, :ortho) \ SVector(x, y, T(0), T(1))
         draw_axes!(plot, x, y, z, args...)