yard-virtus2 0.0.5

data/lib/yard/virtus/declarations/virtus_attribute.rb

@@ -0,0 +1,73 @@
+module YARD
+  module Virtus
+    module Declarations
+      # VirtusModel declaration wraps AST which represents
+      # call to `attribute` method.
+      # It's job is to provide information which documents attribute.
+      class VirtusAttribute
+        attr_reader :ast
+
+        # @param [YARD::Parser::Ruby::MethodCallNode] ast
+        def initialize(ast)
+          @ast = ast
+          @options = Options.new(parameters[2])
+        end
+
+        def readable?
+          true
+        end
+
+        def writable?
+          true
+        end
+
+        # Predicate to check if attribute has private writer.
+        def has_private_writer?
+          options[:writer] == :private
+        end
+
+        # Name of the attribute.
+        # @return [Symbol]
+        def attr_name
+          parameters.first.jump(:ident).first.to_sym
+        end
+
+        # Type of the attribute in YARD format.
+        # @return [String]
+        def type
+          Type.new(type_param).yard_type_string
+        end
+
+        def attribute_reader
+          CodeObjects::AttributeReader.new(attr_name, type)
+        end
+
+        def attribute_writer
+          CodeObjects::AttributeWriter.new(attr_name, type, has_private_writer?)
+        end
+
+        protected
+        attr_reader :options
+
+        def parameters
+          ast.parameters(false)
+        end
+
+        def type_param
+          parameters[1]
+        end
+
+        def scalar_type_to_string(ref)
+          ref.path.join("::")
+        end
+
+        def collection_type_to_string(type)
+          collection_type = scalar_type_to_string(type_param[0])
+          element_type    = scalar_type_to_string(type_param[1].jump(:var_ref))
+
+          "#{collection_type}<#{element_type}>"
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/declarations/virtus_model.rb

@@ -0,0 +1,40 @@
+module YARD
+  module Virtus
+    module Declarations
+      # VirtusModel declaration wraps AST which represents mixin of Virtus.
+      # It's job is to provide information about Virtus features mixed-in
+      # via Virtus declaration.
+      #
+      # @example
+      #   # This is AST for mixin source of `include Virtus.model`.
+      #   ast   = s(:call, s(:var_ref, s(:const, "Virtus")),
+      #                    :".",
+      #                    s(:ident, "model"))
+      #
+      #   model = YARD::Virtus::Declarations::VirtusModel.new(ast)
+      #   model.module_proxies_in_ns(ns) # => P("Virtus.model")
+      class VirtusModel
+        attr_reader :ast
+
+        # @param [YARD::Parser::Ruby::MethodCallNode] ast
+        def initialize(ast)
+          @ast = ast
+        end
+
+        # Get list of proxies to modules which document fetaures inherited
+        # via mixin.
+        #
+        # @param [YARD::CodeObjects::ClassObject] namespace
+        # @return [Array<YARD::CodeObjects::Proxy>]
+        def module_proxies_in_ns(namespace)
+          [YARD::CodeObjects::Proxy.new(namespace, mixin_name, :module)]
+        end
+
+        protected
+        def mixin_name
+          "%s.%s" % [ast.namespace, ast.method_name].map(&:source)
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/handlers.rb

@@ -0,0 +1,2 @@
+require File.join(File.dirname(__FILE__), "handlers", "include_virtus_model")
+require File.join(File.dirname(__FILE__), "handlers", "virtus_attribute")

data/lib/yard/virtus/handlers/include_virtus_model.rb

@@ -0,0 +1,32 @@
+module YARD
+  module Virtus
+    module Handlers
+      class IncludeVirtusModel < YARD::Handlers::Ruby::Base
+        handles method_call(:include)
+        namespace_only
+
+        def process
+          raise YARD::Handlers::HandlerAborted unless virtus_module?
+
+          declaration = Declarations::VirtusModel.new(virtus_call)
+          declaration.module_proxies_in_ns(namespace).each do |proxy|
+            namespace.mixins(scope).unshift(proxy)
+          end
+
+          namespace[:supports_virtus_attributes] = true
+        end
+
+        protected
+
+        def virtus_module?
+          included_module = statement.parameters.jump(:var_ref)
+          included_module and included_module.source == "Virtus"
+        end
+
+        def virtus_call
+          statement.parameters(false)[0]
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/handlers/virtus_attribute.rb

@@ -0,0 +1,58 @@
+module YARD
+  module Virtus
+    module Handlers
+      class VirtusAttribute < YARD::Handlers::Ruby::Base
+        handles method_call(:attribute)
+        namespace_only
+
+        def process
+          raise YARD::Handlers::HandlerAborted unless virtus_model?
+
+          declaration = Declarations::VirtusAttribute.new(statement)
+
+
+          register_attribute!(declaration.attribute_reader, :read)  if declaration.readable?
+          register_attribute!(declaration.attribute_writer, :write) if declaration.writable?
+        end
+
+        protected
+
+        # @param [CodeObjects::AttributeReader, CodeObjects::AttributeWriter] mobject
+        # @param [YARD::CodeObjects::MethodObject] mobject
+        # @param [:read, :write] type
+        def register_attribute!(mobject, type)
+          yard_mobject = mobject.yard_method_object(namespace)
+
+          register_preserving_tags!(yard_mobject)
+          attributes_data_for(mobject.attr_name)[type] = yard_mobject
+        end
+
+        def attributes_data_for(name)
+          namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
+        end
+
+        def virtus_model?
+          namespace.inheritance_tree(true).any? { |n| n[:supports_virtus_attributes] == true }
+        end
+
+        # When you register an object it can get assigned docstring which
+        # followed statement which was handled. If such a docstring exists it
+        # can result in removal of previously extracted tags like `@return` and
+        # `@private` as well as default values. To prevent it we restore all
+        # tags which disappeared after registration.
+        #
+        # Do you love uncontrolled mutations as much as I do?
+        def register_preserving_tags!(object)
+          tags_before_registration = object.tags
+
+          register(object)
+
+          lost_tags = tags_before_registration - object.tags
+          if lost_tags.size > 0
+            object.add_tag(*lost_tags)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/mixin_handler_monkey_patch.rb

@@ -0,0 +1,25 @@
+# Standard YARD mixin handler can not process mixins which include method call.
+# It throws UndocumentableError when it encounters any virtus mixin because they
+# all include method call:
+#
+#     [warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class City
+#     [warn]:   in file 'example/city.rb':2:
+#
+#           2: include Virtus.model
+#
+# This monkey patch aborts parsing of statement instead of raising UndocumentableError.
+class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
+  protected
+  alias_method :original_process_mixin, :process_mixin
+
+  def process_mixin(mixin)
+    raise YARD::Handlers::HandlerAborted if virtus_module?(mixin)
+
+    original_process_mixin(mixin)
+  end
+
+  def virtus_module?(mixin)
+    included_module = mixin.jump(:var_ref)
+    included_module and included_module.source == "Virtus"
+  end
+end

data/lib/yard/virtus/version.rb

@@ -0,0 +1,5 @@
+module YARD
+  module Virtus
+    VERSION = "0.0.5"
+  end
+end

data/spec/code_objects/attribute_reader_spec.rb

@@ -0,0 +1,38 @@
+require "spec_helper"
+
+describe YARD::Virtus::CodeObjects::AttributeReader do
+  subject { described_class.new(:title, "String") }
+
+  it "has #attr_name" do
+    expect(subject.attr_name).to eq(:title)
+  end
+
+  it "has #type" do
+    expect(subject.type).to eq("String")
+  end
+
+  it "has #method_name" do
+    expect(subject.method_name).to eq(:title)
+  end
+
+  describe "#yard_method_object" do
+    let(:reader)    { described_class.new(:title, "String") }
+    let(:namespace) { YARD::CodeObjects::ClassObject.new(nil, "TemporarySpecClass") }
+
+    subject { reader.yard_method_object(namespace) }
+
+    it { expect(subject).to be_instance_of(YARD::CodeObjects::MethodObject) }
+
+    it "is not explicit" do
+      expect(subject.is_explicit?).to be_false
+    end
+
+    it "has the same name as attribute it reads" do
+      expect(subject.name).to eq(:title)
+    end
+
+    it "has @return tag" do
+      expect(subject.has_tag?(:return)).to be_true
+    end
+  end
+end

data/spec/code_objects/attribute_writer_spec.rb

@@ -0,0 +1,75 @@
+require "spec_helper"
+
+describe YARD::Virtus::CodeObjects::AttributeWriter do
+  before :each do
+    # All YARD::CodeObjects::* objects are added to
+    # registry on creation which causes conflicts in
+    # this test.
+    YARD::Registry.clear
+  end
+
+  subject { described_class.new(:title, "String") }
+
+  it "has #attr_name" do
+    expect(subject.attr_name).to eq(:title)
+  end
+
+  it "has #type" do
+    expect(subject.type).to eq("String")
+  end
+
+  it "has #method_name" do
+    expect(subject.method_name).to eq(:"title=")
+  end
+
+  describe "#yard_method_object" do
+    let(:writer)    { described_class.new(:title, "String") }
+    let(:namespace) { YARD::CodeObjects::ClassObject.new(nil, "TemporarySpecClass") }
+
+    subject { writer.yard_method_object(namespace) }
+
+    it { expect(subject).to be_instance_of(YARD::CodeObjects::MethodObject) }
+
+    it "is not explicit" do
+      expect(subject.is_explicit?).to be_false
+    end
+
+    it "has the writer name for attribute" do
+      expect(subject.name).to eq(:"title=")
+    end
+
+    it "has parameter" do
+      expect(subject.parameters).not_to be_empty
+    end
+
+    it "has type signature tag for parameter" do
+      param_tags = subject.tags(:param).select { |t| t.name == "value" }
+
+      expect(param_tags).not_to be_empty
+    end
+
+    context "when writer visibility is not specified" do
+      let(:writer) { described_class.new(:title, "String") }
+
+      it "does not have @private tag" do
+        expect(subject.tags(:private)).to be_empty
+      end
+    end
+
+    context "when writer is public" do
+      let(:writer) { described_class.new(:title, "String", false) }
+
+      it "does not have @private tag" do
+        expect(subject.tags(:private)).to be_empty
+      end
+    end
+
+    context "when writer is private" do
+      let(:writer) { described_class.new(:title, "String", true) }
+
+      it "has @private tag" do
+        expect(subject.tags(:private)).to have(1).item
+      end
+    end
+  end
+end

data/spec/declarations/options_spec.rb

@@ -0,0 +1,50 @@
+require "spec_helper"
+
+describe YARD::Virtus::Declarations::Options do
+  def self.example(src, &block)
+    c = context "'#{src}'"
+    # We can not generate AST for `:a => 1` so we wrap it into
+    # method call like in `attribute :a => 1` and then extract
+    # part corresponding to options. AST for wrapped code will look
+    # like this:
+    #
+    #     s(:command,
+    #       s(:ident, "attribute"),
+    #       s(s(s(:assoc,
+    #             s(:symbol_literal, s(:symbol, s(:ident, "a"))),
+    #             s(:int, "1"))), false))
+    #
+    c.let(:ast) { ruby_ast("attribute #{src}")[1] }
+    c.class_eval(&block)
+  end
+
+  subject { described_class.new(ast) }
+
+  example "" do
+    it { expect(subject).to be_empty }
+  end
+
+  example ":a => :b" do
+    it { expect(subject).not_to be_empty }
+
+    it "has information about key :a" do
+      expect(subject[:a]).to eq(:b)
+    end
+  end
+
+  example "a: :b" do
+    it { expect(subject).not_to be_empty }
+
+    it "has information about key :a" do
+      expect(subject[:a]).to eq(:b)
+    end
+  end
+
+  example ":default => lambda { 123 }" do
+    it { expect(subject).not_to be_empty }
+
+    it "has information about lambda function" do
+      expect(subject[:default]).to be_kind_of(Proc)
+    end
+  end
+end

data/spec/declarations/type_spec.rb

@@ -0,0 +1,37 @@
+require "spec_helper"
+
+describe YARD::Virtus::Declarations::Type do
+  def self.example(src, &block)
+    c = context "'#{src}'"
+    c.let(:ast) { ruby_ast(src) }
+    c.class_eval(&block)
+  end
+
+  describe "#yard_type_string" do
+    let(:subject) { described_class.new(ast).yard_type_string }
+
+    example "String" do
+      it { expect(subject).to eq "String" }
+    end
+
+    example "Some::Nested::String" do
+      it { expect(subject).to eq "Some::Nested::String" }
+    end
+
+    example "Array[String]" do
+      it { expect(subject).to eq "Array<String>" }
+    end
+
+    example "Array[Nested::String]" do
+      it { expect(subject).to eq "Array<Nested::String>" }
+    end
+
+    example "Collection[Address]" do
+      it { expect(subject).to eq "Collection<Address>" }
+    end
+
+    example "Hash[String => Integer]" do
+      it { expect(subject).to eq "Hash{String => Integer}" }
+    end
+  end
+end