Merge pull request #45 from red-data-tools/yard

Use YARD

Author: mrkn

.github/workflows/ci.yml

@@ -52,8 +52,8 @@ jobs:
 
     - run: bundle install --jobs 4 --retry 3
 
-    - run: rake
+    - run: bundle exec rake
 
-    - run: rake build
+    - run: bundle exec rake build
 
     - run: gem install pkg/*.gem

.yardopts

@@ -0,0 +1,6 @@
+--output-dir doc/reference
+--markup markdown
+--no-private
+lib/**/*.rb
+-
+doc/text/*

Gemfile

@@ -1,3 +1,6 @@
 source "https://rubygems.org/"
 
 gemspec
+
+# Temporary use this for module_function decorator support
+gem "yard", github: "mrkn/yard", branch: "module_function_decorator"

Rakefile

@@ -1,13 +1,16 @@
 require "bundler/gem_helper"
+require "yard"
 
 base_dir = File.expand_path("..", __FILE__)
 helper = Bundler::GemHelper.new(base_dir)
 helper.install
-spec = helper.gemspec
 
 desc "Run test"
 task :test do
   ruby("test/run-test.rb")
 end
 
 task default: :test
+
+YARD::Rake::YardocTask.new do |task|
+end

lib/unicode_plot/lineplot.rb

@@ -4,6 +4,32 @@ module UnicodePlot
   class Lineplot < GridPlot
   end
 
+  # @overload lineplot([x], y, name: "", canvas: :braille, title: "", xlabel: "", ylabel: "", labels: true, border: :solid, margin: Plot::DEFAULT_MARGIN, padding: Plot::DEFAULT_PADDING, color: :auto, width: Plot::DEFAULT_WIDTH, height: GridPlot::DEFAULT_HEIGHT, xlim: [0, 0], ylim: [0, 0], canvas: :braille, grid: true)
+  #
+  #   Draws a path through the given points on a new canvas.
+  #
+  #   The first (optional) array `x` should contain the horizontal positions for all the points along the path.
+  #   The second array `y` should then contain the corresponding vertical positions respectively.
+  #   This means that the two vectors must be of the same length and ordering.
+  #
+  #   @param x [Array<Numeric>] Optional. The horizontal position for each point. If omitted, the axes of `y` will be used as `x`.
+  #   @param y [Array<Numeric>] The vertical position for each point.
+  #   @param name [String] Annotation of the current drawing to be displayed on the right.
+  #   @param title
+  #   @param xlabel
+  #   @param ylabel
+  #   @param labels
+  #   @param border
+  #   @param margin
+  #   @param padding
+  #   @param color
+  #   @param width
+  #   @param height
+  #   @param xlim
+  #   @param ylim
+  #   @param canvas [Symbol] The type of canvas that should be used for drawing.
+  #   @param grid [true,false] If `true`, draws grid-lines at the origin.
+  #   @return [Lineplot] A plot object.
   module_function def lineplot(*args,
                                canvas: :braille,
                                color: :auto,
@@ -41,6 +67,16 @@ class Lineplot < GridPlot
     end
   end
 
+  # @overload lineplot!(plot, [x], y, name: "", color: :auto)
+  #
+  #   Draws a path through the given points on the given canvas.
+  #
+  #   @param plot [Lineplot] The plot object.
+  #   @param x [Array<Numeric>] Optional. The horizontal position for each point. If omitted, the axes of `y` will be used as `x`.
+  #   @param y [Array<Numeric>] The vertical position for each point.
+  #   @param name [String] Annotation of the current drawing to be displayed on the right.
+  #   @param color
+  #   @return [Lineplot] The plot object same as the `plot` parameter.
   module_function def lineplot!(plot,
                                 *args,
                                 color: :auto,

lib/unicode_plot/stairs.rb

@@ -1,58 +1,54 @@
 # coding: utf-8
 module UnicodePlot
-  # == Description
+  # @overload stairs(x, y, style: :post, name: "", title: "", xlabel: "", ylabel: "", labels: true, border: :solid, margin: 3, padding: 1, color: :auto, width: 40, height: 15, xlim: [0, 0], ylim: [0, 0], canvas: :braille, grid: true)
   #
-  # Draws a staircase plot on a new canvas.
+  #   Draws a staircase plot on a new canvas.
   #
-  # The first 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.
+  #   The first 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.
   #
-  # == Usage
+  #   @param x [Array<Numeric>] The horizontal position for each point.
+  #   @param y [Array<Numeric>] The vertical position for each point.
+  #   @param style [Symbol] Specifies where the transition of the stair takes place. Can be either `:pre` or `:post`.
+  #   @param name [String] Annotation of the current drawing to be displayed on the right.
+  #   @param height [Integer] Number of character rows that should be used for plotting.
+  #   @param xlim [Array<Numeric>] Plotting range for the x axis. `[0, 0]` stands for automatic.
+  #   @param ylim [Array<Numeric>] Plotting range for the y axis. `[0, 0]` stands for automatic.
+  #   @param canvas [Symbol] The type of canvas that should be used for drawing.
+  #   @param grid [Boolean] If `true`, draws grid-lines at the origin.
   #
-  #     UnicodePlot.stairs(x, y, style: :post, name: "", title: "", xlabel: "", ylabel: "", labels: true, border: :solid, margin: 3, padding: 1, color: :auto, width: 40, height: 15, xlim: [0, 0], ylim: [0, 0], canvas: :braille, grid: true)
+  #   @return [Plot] A plot object.
   #
-  # @param x [Array<Numeric>] The horizontal position for each point.
-  # @param y [Array<Numeric>] The vertical position for each point.
-  # @param style [Symbol] Specifies where the transition of the stair takes place. Can be either `:pre` or `:post`.
-  # @param name [String] Annotation of the current drawing to be displayed on the right.
-  # @param height [Integer] Number of character rows that should be used for plotting.
-  # @param xlim [Array<Numeric>] Plotting range for the x axis. `[0, 0]` stands for automatic.
-  # @param ylim [Array<Numeric>] Plotting range for the y axis. `[0, 0]` stands for automatic.
-  # @param canvas [Symbol] The type of canvas that should be used for drawing.
-  # @param grid [Boolean] If `true`, draws grid-lines at the origin.
+  #   @example Example usage of stairs on IRB:
   #
-  # @return [Plot] A plot object
-  #
-  # @example
-  #   UnicodePlot.stairs([1, 2, 4, 7, 8], [1, 3, 4, 2, 7], style: :post, title: "My Staircase Plot")
-  #
-  #
-  #     ┌────────────────────────────────────────┐
-  #   7 │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⡄⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⢸⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⢸│
-  #     │⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠧⠤⠤⠤⠤⠼│
-  #     │⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
-  #   1 │⣀⣀⣀⣀⣀⣸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
-  #     └────────────────────────────────────────┘
-  #     1                                        8
-  #
-  # @see Plot
-  # @see scatterplot
-  # @see lineplot
+  #       >> UnicodePlot.stairs([1, 2, 4, 7, 8], [1, 3, 4, 2, 7], style: :post, title: "My Staircase Plot").render
+  #                        My Staircase Plot
+  #            ┌────────────────────────────────────────┐
+  #          7 │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⡄⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⢸⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⢸│
+  #            │⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠧⠤⠤⠤⠤⠼│
+  #            │⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
+  #          1 │⣀⣀⣀⣀⣀⣸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
+  #            └────────────────────────────────────────┘
+  #            1                                        8
+  #       => nil
   #
+  #   @see Plot
+  #   @see scatterplot
+  #   @see lineplot
   module_function def stairs(xvec, yvec, style: :post, **kw)
     x_vex, y_vex = compute_stair_lines(xvec, yvec, style: style)
     lineplot(x_vex, y_vex, **kw)

unicode_plot.gemspec

@@ -34,4 +34,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", ">= 1.17"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "test-unit"
+  spec.add_development_dependency "yard"
 end