yard-virtus2 0.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0ae62b7d9da5e4d35e74362a3d73c7cd4353ea2feddc511a5376e38458d0ac6a
+  data.tar.gz: 2238ad54bd66edc345d6559799e52b8f88e9a7596581773cb6791c06a67f0eae
+SHA512:
+  metadata.gz: de41f36807697d23143d8e889ff7624a846beed3d020d6a35812d796d1adf08bf91aec7a233c3c7aec89930ea6909bec0a29e15f6f5f75fd91b51a3eef22f46f
+  data.tar.gz: 015f709229bfc35820b6f88cbd0fea86a687598af4c0045bd7ef33dc1fd4310e7f7b1ca1a4e16d4578ffa04e705671ac4220cf9b194df189b9b6d89557825236

data/.gitignore

@@ -0,0 +1,24 @@
+# Ignore bundler config and scripts/binaries
+/.bundle
+/.bin
+
+# Ignore YARD run-off
+.yardoc/
+
+# Ignore automatically generated documentation
+# for sample project
+example/doc
+
+doc
+
+.DS_Store
+*~
+*#
+*.o
+*.dylib
+*.a
+*.so
+.#*
+*.rbc
+.rvmrc
+tmp/

data/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/yard-virtus.iml" filepath="$PROJECT_DIR$/.idea/yard-virtus.iml" />
+    </modules>
+  </component>
+</project>

data/Gemfile

@@ -0,0 +1,17 @@
+source "https://rubygems.org"
+
+gem "virtus", "= 1.0.2"
+gem "yard", "= 0.8.7.4"
+
+group :development do
+  gem "rspec"
+
+  gem "guard-rspec", "~> 4.2.9", require: false
+  gem "terminal-notifier-guard"
+
+  gem "rake"
+  gem "pry"
+
+  # Github Flavored Markdown support
+  gem "redcarpet"
+end

data/Gemfile.lock

@@ -0,0 +1,75 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    axiom-types (0.1.1)
+      descendants_tracker (~> 0.0.4)
+      ice_nine (~> 0.11.0)
+      thread_safe (~> 0.3, >= 0.3.1)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    coderay (1.1.0)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.2.5)
+    equalizer (0.0.9)
+    ffi (1.9.3)
+    formatador (0.2.5)
+    guard (2.6.1)
+      formatador (>= 0.2.4)
+      listen (~> 2.7)
+      lumberjack (~> 1.0)
+      pry (>= 0.9.12)
+      thor (>= 0.18.1)
+    guard-rspec (4.2.9)
+      guard (~> 2.1)
+      rspec (>= 2.14, < 4.0)
+    ice_nine (0.11.0)
+    listen (2.7.5)
+      celluloid (>= 0.15.2)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.6)
+    method_source (0.8.2)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rake (10.3.2)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.4)
+      ffi (>= 0.5.0)
+    redcarpet (3.1.2)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+    slop (3.5.0)
+    terminal-notifier-guard (1.5.3)
+    thor (0.19.1)
+    thread_safe (0.3.3)
+    timers (1.1.0)
+    virtus (1.0.2)
+      axiom-types (~> 0.1)
+      coercible (~> 1.0)
+      descendants_tracker (~> 0.0.3)
+      equalizer (~> 0.0.9)
+    yard (0.8.7.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard-rspec (~> 4.2.9)
+  pry
+  rake
+  redcarpet
+  rspec
+  terminal-notifier-guard
+  virtus (= 1.0.2)
+  yard (= 0.8.7.4)

data/Guardfile

@@ -0,0 +1,11 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cmd: "bundle exec rspec" do
+  watch(%r{^spec/(.+)/.+_spec\.rb$})
+
+  watch(%r{^lib/yard/virtus/(.+)/(.+)\.rb$}) { |m| "spec/#{m[1]}/#{m[2]}_spec.rb" }
+
+  watch('spec/spec_helper.rb')       { "spec" }
+  watch(%r{spec/support/(.+)/*.rb$}) { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Dmitry Dzema
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,61 @@
+# yard-virtus
+
+
+This gem helps to generate YARD documentation for classes built using [Virtus](https://github.com/solnic/virtus). It extracts information about attributes, their types and writers so you don't need to specify it manually.
+
+This gem depends on exact details of implementation of Virtus so it's locked to a particular version. In the future I wan to adapt versioning scheme for this gem which will reflect supported Virtus version.
+
+## Install
+
+Add the gem to your Gemfile (inside development or documentation group):
+
+``` ruby
+  gem "yard-virtus", "= 0.0.4"
+```
+
+## Usage
+
+If you use YARD via Rake and `YARD::Rake::YardocTask` or via custom ruby script add
+
+``` ruby
+  require "yard-virtus"
+```
+
+If you use YARD command line tool use `--plugin` switch like this
+
+```shell
+ yard --plugin virtus
+```
+
+### Workaround for UndocumentableError Warnings
+
+Standard YARD mixin handler throws `UndocumentableError` when it encounters
+mixin which uses method call (like `include Virtus.model`). It serves as a warning
+and does not break parsing process but it could be annoying if you have a lot
+of Virtus based models. This gem includes mokey-patch for `YARD::Handlers::Ruby::MixinHandler`.
+It is not loaded by default and you need to do it explicitly in your Rakefile with:
+
+```ruby
+  require "yard/virtus/mixin_handler_monkey_patch"
+```
+
+## Work in Progress
+
+This library is still work in progress and is not recommended for production use.
+
+### TODO
+
+* Detect if class gets virtus functionality via inheritance (partially done).
+* Attach documentation about various features inherited from Virtus to namespaces.
+* Extract default values of attributes.
+
+## Notice
+
+This library uses eval with $SAFE level 3 to evaluate list of options in
+`attribute` declarations. Setting $SAFE to level 3 means it can not do
+destructive operations on your file system but it can damage objects which
+are already in memory.
+
+### Author
+
+[Dmitry Dzema](https://github.com/DimaD) ([@dzema](https://twitter.com/dzema))

data/Rakefile

@@ -0,0 +1,9 @@
+require File.join(File.dirname(__FILE__), "lib", "yard-virtus")
+require File.join(File.dirname(__FILE__), "lib", "yard-virtus")
+require File.join(File.dirname(__FILE__), "lib", "yard/virtus/mixin_handler_monkey_patch")
+
+desc "Build documentation for sample code set"
+YARD::Rake::YardocTask.new("example") do |t|
+  t.files   = ["example/**/*.rb"]
+  t.options = ["--no-private", "--markup-provider=redcarpet", "--markup=markdown", "--output-dir=./example/doc"]
+end

data/example/README.md

@@ -0,0 +1,4 @@
+# virtus-yardoc example
+
+This is a simple project to demonstrate virtus-yard features.
+Code here is devised from main Virtus reame.

data/example/address.rb

@@ -0,0 +1,7 @@
+class Address
+  include Virtus.model
+
+  attribute :street,  String
+  attribute :zipcode, String
+  attribute :city,    City
+end

data/example/city.rb

@@ -0,0 +1,5 @@
+class City
+  include Virtus.model
+
+  attribute :name, String
+end

data/example/user.rb

@@ -0,0 +1,9 @@
+class User
+  include Virtus.model
+
+  attribute :name, String
+  attribute :age, Integer
+
+  # User can have work address or home address
+  attribute :addresses, Array[Address]
+end

data/lib/yard-virtus.rb

@@ -0,0 +1,18 @@
+require "virtus"
+require "yard"
+
+_dir = File.dirname(__FILE__)
+require File.join(_dir, "yard", "virtus", "version")
+
+require File.join(_dir, "yard", "virtus", "handlers")
+require File.join(_dir, "yard", "virtus", "declarations")
+require File.join(_dir, "yard",  "virtus", "code_objects")
+
+# According to ruby conventions if library is called
+# `yard-virtus` it should be included via
+#
+#     require "yard/virtus"
+#
+# But YARD plugins do not follow this convention and require
+# gem names like `yard-*` and being required by the same name.
+# Hence this confusing filename.

data/lib/yard/virtus/code_objects.rb

@@ -0,0 +1,2 @@
+require File.join(File.dirname(__FILE__), "code_objects", "attribute_reader")
+require File.join(File.dirname(__FILE__), "code_objects", "attribute_writer")

data/lib/yard/virtus/code_objects/attribute_reader.rb

@@ -0,0 +1,26 @@
+module YARD
+  module Virtus
+    module CodeObjects
+      class AttributeReader
+        attr_reader :attr_name, :type
+
+        # @param [Symbol] attr name of attribute
+        # @param [String] type string representation of type in YARD format
+        def initialize(attr, type)
+          @attr_name = attr
+          @type      = type
+        end
+
+        def method_name
+          attr_name
+        end
+
+        def yard_method_object(namespace)
+          YARD::CodeObjects::MethodObject.new(namespace, method_name, :instance).tap do |mo|
+            mo.add_tag YARD::Tags::Library.new.return_tag("[#{type}]")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/code_objects/attribute_writer.rb

@@ -0,0 +1,48 @@
+module YARD
+  module Virtus
+    module CodeObjects
+      class AttributeWriter
+        attr_reader :attr_name, :type
+
+        # @param [Symbol] attr name of attribute
+        # @param [String] type string representation of type in YARD format
+        # @param [Boolean] is_private indicates if writer is part of private API
+        def initialize(attr, type, is_private=false)
+          @attr_name = attr
+          @type      = type
+          @is_private = is_private
+        end
+
+        def method_name
+          :"#{attr_name}="
+        end
+
+        def yard_method_object(namespace)
+          YARD::CodeObjects::MethodObject.new(namespace, method_name, :instance).tap do |mo|
+            mo.parameters = [["value", default_value]]
+            mo.add_tag param_tag("value", type)
+            mo.add_tag private_tag if private?
+          end
+        end
+
+        protected
+
+        def default_value
+          nil
+        end
+
+        def private?
+          !!@is_private
+        end
+
+        def param_tag(param_name, param_type)
+          YARD::Tags::Tag.new("param", nil, param_type, param_name)
+        end
+
+        def private_tag
+          YARD::Tags::Tag.new("private", "")
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/declarations.rb

@@ -0,0 +1,4 @@
+require File.join(File.dirname(__FILE__), "declarations", "virtus_model")
+require File.join(File.dirname(__FILE__), "declarations", "virtus_attribute")
+require File.join(File.dirname(__FILE__), "declarations", "type")
+require File.join(File.dirname(__FILE__), "declarations", "options")

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

@@ -0,0 +1,53 @@
+module YARD
+  module Virtus
+    module Declarations
+      # Options declaration wraps AST which represents
+      # options hash.
+      #
+      # @example
+      #     # this is AST for hash part of call `hello :default => 0, :writer => :private`
+      #     ast = s(s(:assoc, s(:symbol_literal, s(:symbol, s(:ident, "default"))),
+      #                       s(:int, "0")),
+      #             s(:assoc, s(:symbol_literal, s(:symbol, s(:ident, "writer"))),
+      #                       s(:symbol_literal, s(:symbol, s(:ident, "private")))))
+      #     options = YARD::Virtus::Declarations::Options.new(ast)
+      #     options[:writer] # => :private
+      class Options
+        attr_reader :ast
+
+        # @param [YARD::Parser::Ruby::AstNode, nil] ast
+        def initialize(ast)
+          @ast = ast
+          @data = if ast.kind_of?(YARD::Parser::Ruby::AstNode)
+                    safe_eval("{#{ast.source}}")
+                  else
+                    {}
+                  end
+        end
+
+        # Get option value by key.
+        def [](key)
+          data[key]
+        end
+
+        # Predicate to check if there are any options.
+        def empty?
+          data.empty?
+        end
+
+        protected
+        attr_reader :data
+
+        # It's not the best idea to use eval but interpreting AST tree to search for hash
+        # values is not fun either.
+        # @todo replace with AST tree interpreter
+        def safe_eval(source)
+          proc do |src|
+            $SAFE = 3;
+            eval(src)
+          end.call(source.untaint)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module YARD
+  module Virtus
+    module Declarations
+      # Type declaration wraps AST which represents type of Virtus attribute.
+      # It's job is to translate AST into type string which YARD can understand.
+      #
+      # @example
+      #     # this is AST for `Array[String]`.
+      #     ast  = s(:aref, s(:var_ref, s(:const, "Array")),
+      #                     s(s(:var_ref, s(:const, "String")), false))
+      #
+      #     type = YARD::Virtus::Declarations::Type.new(ast)
+      #     type.yard_type_string # => "Array<String>"
+      class Type
+        attr_reader :ast
+
+        # @param [YARD::Parser::Ruby::ReferenceNode, YARD::Parser::Ruby::AstNode] ast
+        def initialize(ast)
+          @ast = ast
+        end
+
+        # Get type string for provided AST.
+        #
+        # @return [String] if provided AST can be transformed into type
+        # @return [nil] if can not transform AST into type string
+        def yard_type_string
+          if association?(ast)
+            yard_type_from_association(ast)
+          elsif collection?(ast)
+            yard_type_from_collection(ast)
+          elsif ast.ref?
+            yard_type_from_reference(ast)
+          elsif !ast[0].nil?
+            Type.new(ast[0]).yard_type_string
+          else
+            nil
+          end
+        end
+
+        protected
+        def yard_type_from_reference(tree)
+          tree.path.join("::")
+        end
+
+        def yard_type_from_association(tree)
+          collection = tree[0].jump(:var_ref)
+          key, value = extract_kv_from_association(ast[1])
+
+          "%s{%s => %s}" % [collection, key, value].map { |type| Type.new(type).yard_type_string }
+        end
+
+        def yard_type_from_collection(ast)
+          "%s<%s>" % [ast[0], ast[1]].map { |type| Type.new(type).yard_type_string }
+        end
+
+        def association?(tree)
+          tree.jump(:assoc) != tree
+        end
+
+        def collection?(tree)
+          tree.type == :aref
+        end
+        def extract_kv_from_association(tree)
+          assoc = tree.jump(:assoc)
+
+          return assoc[0], assoc[1]
+        end
+      end
+    end
+  end
+end