How to document dynamically defined methods in YARD

[heronshoes]

Vector functions such as #mean, #abs, #>, etc. are dynamically created by define_method using Arrow's compute functions in RedAmber. But I had no idea to document them in YARD. I finally found a solution and updated (#129). I will take a note here.

Use Class method to define methods

Make a class method to define method and use it like DSL.

class Vector
  class << self
    private

    def define_unary_aggregation(function)
      define_method(function) do |**options|
        datum = exec_func_unary(function, options)
        get_scalar(datum)
      end
    end
  end

  define_unary_aggregation :approximate_median
end

Document them

• Attach documents in class method for common documents with @!macro (1).

• Non-attaching (new) macros are defined for the options (2).

• Main part of the document are defined on the top of method (3).

• @!method will properly define arguments and default options (4).

• Aliases should be defined by alias_method (5). It can be defined by class method in some cases, but alias_method can handle Also known as:.

  class Vector
    class << self
      private
  
      # @!macro [attach] define_unary_aggregation         # (1)
      #   [Unary aggregation function] Returns a scalar.
      #
      def define_unary_aggregation(function)
        define_method(function) do |**options|
          datum = exec_func_unary(function, options)
          get_scalar(datum)
        end
      end
    end
  
    # @!macro scalar_aggregate_options                    # (2)
    #   @param skip_nulls [true, false]
    #     If true, nil values are ignored.
    #     Otherwise, if any value is nil, emit nil.
    #   @param min_count [Integer]
    #     if less than this many non-nil values are observed, emit nil.
    #     If skip_nulls is false, this option is not respected.
  
    # Approximate median of a numeric Vector with T-Digest algorithm.   # (3)
    #
    # @!method approximate_median(skip_nulls: true, min_count: 1)       # (4)
    # @macro scalar_aggregate_options                    # (2)
    # @return [Float]
    #   median of self.
    #   A nil is returned if there is no valid data point.
    #
    define_unary_aggregation :approximate_median
    alias_method :median, :approximate_median            # (5)
  end

Results are: https://heronshoes.github.io/red_amber/RedAmber/Vector.html#approximate_median-instance_method

YARD document: https://rubydoc.info/gems/yard/file/docs/Tags.md#macro