yard-activerecord 0.0.5

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in yard-activerecord.gemspec
+gemspec

data/README.md

@@ -0,0 +1,59 @@
+# YARD ActiveRecord Plugin #
+
+A YARD extension that handles and interprets methods used when developing
+applications with ActiveRecord. The extension handles attributes,
+associations, delegates and scopes. A must for any Rails app using YARD as
+documentation plugin.
+
+## Attributes ##
+
+In order for this plugin to document any database attributes you need to add
+`schema.rb` to your list of files. This is preferably done with in `.yardopts`.
+
+The `schema.rb`-file should be added at the end as it needs all classes loaded
+before it can add the attributes.
+
+The plugin will then document all attributes in your documentation.
+
+All attributes will be marked as writable. I will update the plugin to include
+handling of `attr_accessible` at a later point.
+
+Please note that any reference-fields that ends with `_id` will not be handled
+as an attribute. Please see Associations.
+
+There is an issue with namespaced classes. Currently this plugin will try and
+fetch a class with a namespace if it does not find one at the first try.
+
+Example:
+
+    Table name        Class name
+    sales_people      SalesPeople # does not exist
+    sales_people      Sales::People # does exist
+
+A problem then emerges if you have namespaces with two names.
+
+Example:
+
+    Table name          Class name
+    sales_force_people  SalesForcePeople # does not exist
+    sales_force_people  Sales::ForcePeople # does not exist
+
+The documentation will then be skipped for this table/class.
+
+## Associations ##
+
+The plugin handles `has_one`, `belongs_to`, `has_many` and
+`has_and_belongs_to_many` associations. The annotation for each association
+includes a link to the referred model. For associations with a list of objects
+the documentation will simply be marked as `Array<ModelName>`.
+
+## Delegates ##
+
+The plugin handles `delegate`-methods and marks these delegated instance
+methods simply as aliases for the associated object.
+
+## Scopes ##
+
+The plugin will add class methods for any scopes you have defined in your
+models.
+

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/lib/yard-activerecord.rb

@@ -0,0 +1,20 @@
+require 'yard'
+
+module YARD::Handlers::Ruby::ActiveRecord
+end
+
+root = File.expand_path(File.dirname(__FILE__))
+$LOAD_PATH << root unless $LOAD_PATH.include? root
+
+require 'yard-activerecord/fields/create_table_handler'
+require 'yard-activerecord/fields/define_handler'
+require 'yard-activerecord/fields/field_handler'
+
+require 'yard-activerecord/associations/belongs_to_handler'
+require 'yard-activerecord/associations/has_one_handler'
+require 'yard-activerecord/associations/has_many_handler'
+require 'yard-activerecord/associations/has_and_belongs_to_many_handler'
+
+require 'yard-activerecord/delegations/delegate_handler'
+
+require 'yard-activerecord/scopes/scope_handler'

data/lib/yard-activerecord/associations/base.rb

@@ -0,0 +1,53 @@
+require 'yard'
+require 'active_support/inflector'
+
+module YARD::Handlers::Ruby::ActiveRecord::Associations
+  class Base < YARD::Handlers::Ruby::MethodHandler
+    namespace_only
+
+    def process
+      group_name = "Active Record Associations"
+      namespace.groups << group_name unless namespace.groups.include? group_name
+
+      object           = YARD::CodeObjects::MethodObject.new(namespace, method_name)
+      object.group     = group_name
+      object.docstring = return_description
+      object.docstring.add_tag get_tag(:return, '', class_name)
+      object.docstring.add_tag get_tag(:see, 'http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html')
+      object.dynamic = true
+      register object
+    end
+
+    private
+    def method_name
+      call_params[0]
+    end
+
+    def class_name(singularize = false)
+      param_size = statement.parameters.size
+      if param_size > 2
+        i           = 1
+        return_this = false
+        while i < param_size - 1
+          # May want to evaluate doing it this way
+          statement.parameters[i].jump(:hash).source =~ /(:class_name\s*=>|class_name:)\s*["']([^"']+)["']/
+          return $2 if $2
+          i += 1
+        end
+      end
+      if singularize == true
+        ActiveSupport::Inflector.singularize method_name.capitalize
+      else
+        method_name.capitalize
+      end
+    end
+
+    def return_description
+      "An array of associated #{method_name}."
+    end
+
+    def get_tag(tag, text, return_classes = [])
+      YARD::Tags::Tag.new(tag, text, [return_classes].flatten)
+    end
+  end
+end

data/lib/yard-activerecord/associations/belongs_to_handler.rb

@@ -0,0 +1,12 @@
+require_relative 'singular_handler'
+
+module YARD::Handlers::Ruby::ActiveRecord::Associations
+  class BelongsToHandler < SingularHandler
+    handles method_call(:belongs_to)
+
+    private
+    def return_description
+      "#{namespace} <b>belongs to</b> a #{class_name}"
+    end
+  end
+end

data/lib/yard-activerecord/associations/has_and_belongs_to_many_handler.rb

@@ -0,0 +1,11 @@
+require_relative 'plural_handler'
+
+module YARD::Handlers::Ruby::ActiveRecord::Associations
+  class HasAndBelongsToManyHandler < PluralHandler
+    handles method_call(:has_and_belongs_to_many)
+
+    def return_description
+      "#{namespace} <b>has and belongs to many</b> #{method_name}"
+    end
+  end
+end

data/lib/yard-activerecord/associations/has_many_handler.rb

@@ -0,0 +1,11 @@
+require_relative 'plural_handler'
+
+module YARD::Handlers::Ruby::ActiveRecord::Associations
+  class HasManyHandler < PluralHandler
+    handles method_call(:has_many)
+
+    def return_description
+      "#{namespace} <b>has many</b> #{method_name}"
+    end
+  end
+end

data/lib/yard-activerecord/associations/has_one_handler.rb

@@ -0,0 +1,11 @@
+require_relative 'singular_handler'
+
+module YARD::Handlers::Ruby::ActiveRecord::Associations
+  class HasOneHandler < SingularHandler
+    handles method_call(:has_one)
+
+    def return_description
+      "#{namespace} <b>has one</b> #{method_name}"
+    end
+  end
+end

data/lib/yard-activerecord/associations/plural_handler.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+
+module YARD::Handlers::Ruby::ActiveRecord::Associations
+  class PluralHandler < Base
+    def class_name
+      "Array<#{super(true)}>"
+    end
+  
+    def return_description
+      "An array of associated #{method_name}"
+    end
+  end
+end

data/lib/yard-activerecord/associations/singular_handler.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+
+module YARD::Handlers::Ruby::ActiveRecord::Associations
+  class SingularHandler < Base
+    def class_name
+      super(false)
+    end
+  
+    def return_description
+      "An associated #{method_name}"
+    end
+  end
+end

data/lib/yard-activerecord/delegations/delegate_handler.rb

@@ -0,0 +1,31 @@
+require 'yard'
+
+module YARD::Handlers::Ruby::ActiveRecord::Delegations
+  class DelegateHandler < YARD::Handlers::Ruby::MethodHandler
+    handles method_call(:delegate)
+    namespace_only
+
+    def process
+      params = call_params
+      class_name = params.pop.capitalize
+      params.each do |method_name|
+        object = YARD::CodeObjects::MethodObject.new(namespace, method_name)
+        object.group = "Delegated Instance Attributes"
+        object.docstring = "Please refer to {#{class_name}##{method_name}}"
+        object.docstring.add_tag get_tag(:return,
+            "{#{class_name}##{method_name}}", 'Object')
+        object.docstring.add_tag get_tag(:see,
+            "http://api.rubyonrails.org/classes/Module.html#method-i-delegate")
+        register object
+      end
+      group_name = "Delegated Instance Attributes"
+      namespace.groups << group_name unless namespace.groups.include? group_name
+    end
+
+    private
+
+    def get_tag(tag, text, return_classes = [])
+      YARD::Tags::Tag.new(tag, text, [return_classes].flatten)
+    end
+  end
+end

data/lib/yard-activerecord/fields/create_table_handler.rb

@@ -0,0 +1,19 @@
+require 'yard'
+require 'active_support/inflector'
+
+module YARD::Handlers::Ruby::ActiveRecord::Fields
+  class CreateTableHandler < YARD::Handlers::Ruby::MethodHandler
+    handles method_call(:create_table)
+
+    def process
+      return unless globals.ar_schema
+      globals.klass = ActiveSupport::Inflector.singularize call_params.first.camelize
+      if P(globals.klass).class == YARD::CodeObjects::Proxy
+        # Try module with the first part
+        globals.klass = globals.klass.underscore.split('_',2).map(&:camelize).join('::')
+      end
+      parse_block(statement.last.last)
+      globals.klass = nil
+    end
+  end
+end

data/lib/yard-activerecord/fields/define_handler.rb

@@ -0,0 +1,13 @@
+module YARD::Handlers::Ruby::ActiveRecord::Fields
+  class DefineHandler < YARD::Handlers::Ruby::MethodHandler
+    handles method_call(:define)
+    
+    def process
+      if statement.file == 'db/schema.rb'
+        globals.ar_schema = true
+        parse_block(statement.last.last)
+        globals.ar_schema = false
+      end
+    end
+  end
+end

data/lib/yard-activerecord/fields/field_handler.rb

@@ -0,0 +1,50 @@
+module YARD::Handlers::Ruby::ActiveRecord::Fields
+  class FieldHandler < YARD::Handlers::Ruby::MethodHandler
+    handles method_call(:string)
+    handles method_call(:text)
+    handles method_call(:integer)
+    handles method_call(:float)
+    handles method_call(:boolean)
+    handles method_call(:datetime)
+  
+    def process
+      return unless statement.namespace.jump(:ident).source == 't'
+      method_name = call_params.first
+      class_name = caller_method.capitalize
+      
+      return if method_name['_id'] # Skip all id fields, associations will handle that
+      
+      if class_name == "Datetime"
+        class_name = "DateTime"
+      end
+      ensure_loaded! P(globals.klass)
+      namespace = P(globals.klass)
+      return if namespace.nil?
+    
+      r_object = YARD::CodeObjects::MethodObject.new(namespace, method_name)
+      r_object.docstring = description(method_name)
+      r_object.docstring.add_tag get_tag(:return, '', class_name)
+      r_object.dynamic = true
+      register r_object
+    
+      w_object = YARD::CodeObjects::MethodObject.new(namespace, "#{method_name}=")
+      w_object.docstring = description(method_name)
+      w_object.docstring.add_tag get_tag(:return, '', class_name)
+      w_object.dynamic = true
+      register w_object
+    
+      namespace.instance_attributes[method_name.to_sym] = {
+        read: r_object,
+        write: w_object
+      }
+    end
+  
+    def description(method_name)
+      "Database field value of #{method_name}. Defined in {file:db/schema.rb}"
+    end
+  
+    def get_tag(tag, text, return_classes)
+      YARD::Tags::Tag.new(:return, text, [return_classes].flatten)
+    end
+  end
+end

data/lib/yard-activerecord/scopes/scope_handler.rb

@@ -0,0 +1,36 @@
+require 'active_support/inflector'
+
+module YARD::Handlers::Ruby::ActiveRecord::Scopes
+  class ScopeHandler < YARD::Handlers::Ruby::MethodHandler
+    handles method_call(:scope)
+    namespace_only
+    
+    def process
+      object = YARD::CodeObjects::MethodObject.new(namespace, method_name, :class)
+      object.docstring = return_description
+      object.docstring.add_tag get_tag(:return, '', class_name)
+      object.docstring.add_tag get_tag(:see,
+'http://api.rubyonrails.org/classes/ActiveRecord/NamedScope/ClassMethods.html')
+      register object
+    end
+    
+    private
+    def method_name
+      call_params[0]
+    end
+    
+    def return_description
+      "An array of #{ActiveSupport::Inflector.pluralize namespace.to_s} " +
+      "that are #{method_name.split('_').join(' ')}. " +
+      "<strong>Active Record Scope</strong>"
+    end
+    
+    def class_name
+      "Array<#{namespace}>"
+    end
+
+    def get_tag(tag, text, return_classes = [])
+      YARD::Tags::Tag.new(tag, text, [return_classes].flatten)
+    end
+  end
+end

data/lib/yard-activerecord/version.rb

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

data/test.rb

@@ -0,0 +1,4 @@
+require 'bundler/setup'
+require 'yard-activerecord'
+
+YARD::Handlers::Ruby::ActiveRecord::Fields::CreateTable.new

data/yard-activerecord.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+require "yard-activerecord/version"
+
+Gem::Specification.new do |s|
+  s.name        = "yard-activerecord"
+  s.version     = YARD::ActiveRecord::VERSION
+  s.authors     = ["Theodor Tonum"]
+  s.email       = ["theodor@tonum.no"]
+  s.homepage    = ""
+  s.summary     = %q{ActiveRecord Handlers for YARD}
+  s.description = %q{
+    YARD-Activerecord is a YARD extension that handles and interprets methods
+    used when developing applications with ActiveRecord. The extension handles
+    attributes, associations, delegates and scopes. A must for any Rails app
+    using YARD as documentation plugin. }
+
+  s.add_dependency 'yard', '>= 0.8.3'
+
+  s.files         = `git ls-files`.split("\n")
+  s.require_path  = "lib"
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: yard-activerecord
+version: !ruby/object:Gem::Version
+  version: 0.0.5
+  prerelease: 
+platform: ruby
+authors:
+- Theodor Tonum
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+description: ! "\n    YARD-Activerecord is a YARD extension that handles and interprets
+  methods\n    used when developing applications with ActiveRecord. The extension
+  handles\n    attributes, associations, delegates and scopes. A must for any Rails
+  app\n    using YARD as documentation plugin. "
+email:
+- theodor@tonum.no
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/yard-activerecord.rb
+- lib/yard-activerecord/associations/base.rb
+- lib/yard-activerecord/associations/belongs_to_handler.rb
+- lib/yard-activerecord/associations/has_and_belongs_to_many_handler.rb
+- lib/yard-activerecord/associations/has_many_handler.rb
+- lib/yard-activerecord/associations/has_one_handler.rb
+- lib/yard-activerecord/associations/plural_handler.rb
+- lib/yard-activerecord/associations/singular_handler.rb
+- lib/yard-activerecord/delegations/delegate_handler.rb
+- lib/yard-activerecord/fields/create_table_handler.rb
+- lib/yard-activerecord/fields/define_handler.rb
+- lib/yard-activerecord/fields/field_handler.rb
+- lib/yard-activerecord/scopes/scope_handler.rb
+- lib/yard-activerecord/version.rb
+- test.rb
+- yard-activerecord.gemspec
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: ActiveRecord Handlers for YARD
+test_files: []
+has_rdoc: