yard-js 0.1.1

data/lib/yard-js/core_ext/yard/templates.rb

@@ -0,0 +1,116 @@
+module YARD
+  module Templates
+    module Helpers
+      module HtmlHelper
+        def link_object(obj, otitle = nil, anchor = nil, relative = true)
+          return otitle if obj.nil?
+          obj = Registry.resolve(object, obj, true, true) if obj.is_a?(String)
+          if !otitle && obj.root?
+            title = "Top Level Namespace"
+          elsif otitle
+            title = otitle.to_s
+          elsif object.is_a?(CodeObjects::Base)
+            # Check if we're linking to a class method in the current
+            # object. If we are, create a title in the format of
+            # "CurrentClass.method_name"
+            title = h(object.relative_path(obj))
+            if obj.is_a?(YARDJS::CodeObjects::PropertyObject) && obj.property_type == :function
+              title += '()'
+            elsif obj.title != obj.path
+              title = h(obj.title)
+            end
+          else
+            title = h(obj.to_s)
+          end
+          return title unless serializer
+          return title if obj.is_a?(CodeObjects::Proxy)
+
+          link = url_for(obj, anchor, relative)
+          link = link ? link_url(link, title, :title => h("#{obj.title} (#{obj.type})")) : title
+          "<span class='object_link'>" + link + "</span>"
+        end
+
+        def signature_types(meth, link = true)
+          meth = convert_method_to_overload(meth)
+          if meth.respond_to?(:object) && !meth.has_tag?(:return)
+            meth = meth.object
+          end
+          return unless meth
+
+          type = options.default_return || ""
+          if meth.tag(:return) && meth.tag(:return).types
+            types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
+            first = link ? h(types.first) : format_types([types.first], false)
+            if types.size == 2 && types.last == 'null'
+              type = first + '<sup>?</sup>'
+            elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
+              type = first + '<sup>+</sup>'
+            elsif types.size > 2
+              type = [first, '...'].join(', ')
+            elsif types == ['void'] && options.hide_void_return
+              type = ""
+            else
+              type = link ? h(types.join(", ")) : format_types(types, false)
+            end
+          elsif !type.empty?
+            type = link ? h(type) : format_types([type], false)
+          end
+          type = "(#{type}) " unless type.empty?
+          type
+        end
+
+        def signature(meth, link = true, show_extras = true, full_attr_name = true)
+          meth = convert_method_to_overload(meth)
+
+          small_type = true
+          type = signature_types(meth, link)
+          args = ''
+          name = meth.name.to_s
+
+          if meth.constructor?
+            type, name = 'new ', meth.namespace.path.gsub(/_\d+/, '')
+          end
+
+          if meth.property_type == :function
+            if meth.parameters
+              args = meth.parameters.map {|n, v| v ? "#{n} = #{v}" : n.to_s }.join(", ")
+            end
+            args = "(#{args})"
+          end
+
+          if YARDJS::Tags::CallbackTag === meth
+            small_type = false
+            type = ''
+            args += ' { ... }'
+          end
+
+          extras = []
+          extras_text = ''
+          if show_extras
+            extras << 'static' if meth.tag(:static)
+            extras << 'readonly' if meth.tag(:readonly)
+            extras << 'writeonly' if meth.tag(:writeonly)
+            extras << 'readwrite' if !meth.tag(:readonly) && !meth.tag(:writeonly) && meth.property_type != :function
+            extras << meth.visibility if meth.visibility != :public
+            extras_text = ' <span class="extras">(' + extras.join(", ") + ')</span>' unless extras.empty?
+          end
+
+          if small_type
+            title = "<small>%s</small><strong>%s</strong>%s" % [type, h(name), args]
+          else
+            title = "%s<strong>%s</strong>%s" % [type, h(name), args]
+          end
+
+          if link
+            link_title = h(name)
+            obj = meth.respond_to?(:object) ? meth.object : meth
+            url = url_for(object, obj)
+            link_url(url, title, :title => link_title) + extras_text
+          else
+            title + extras_text
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard-js/core_ext/yard/yardoc.rb

@@ -0,0 +1,23 @@
+module YARD
+  module CLI
+    class Yardoc
+      def general_options_yardjs(opts)
+        general_options_orig(opts)
+
+        opts.on('--define-class-expr EXPR') do |expr|
+          YARDJS.options.define_class_expression = expr
+        end
+
+        opts.on('--update-class-expr EXPR') do |expr|
+          YARDJS.options.update_class_expression = expr
+        end
+
+        opts.on('--mixin-module-expr EXPR') do |expr|
+          YARDJS.options.mixin_module_expression = expr
+        end
+      end
+      alias general_options_orig general_options
+      alias general_options general_options_yardjs
+    end
+  end
+end

data/lib/yard-js/handlers.rb

@@ -0,0 +1,7 @@
+require_relative 'handlers/base'
+require_relative 'handlers/class_handler'
+require_relative 'handlers/comment_handler'
+require_relative 'handlers/constant_handler'
+require_relative 'handlers/instance_method_handler'
+require_relative 'handlers/mixin_handler'
+require_relative 'handlers/module_handler'

data/lib/yard-js/handlers/base.rb

@@ -0,0 +1,53 @@
+require_relative '../core_ext/yard'
+require_relative '../core_ext/parsejs'
+
+module YARDJS
+  module Handlers
+    class Base < YARD::Handlers::Base
+      include ParseJS::AST
+
+      def self.handles?(node)
+        handlers.any? {|h| node.is_a?(h) }
+      end
+
+      def call_params; [] end
+      def caller_method; nil end
+
+      def parse_block(inner_node, opts = {})
+        push_state(opts) { parser.process([inner_node].flatten) }
+      end
+
+      def handle_default_comments(comments = statement.comments)
+        return if comments.size == 1
+        comments[0...-1].each do |comment|
+          register_docstring(nil, clean_comment(comment.body))
+        end
+
+        if parser.extra_state.ignore_next_statement
+          parser.extra_state.ignore_next_statement = nil
+          abort!
+        end
+      end
+
+      def clean_comment(comment)
+        comment = comment.body if comment.respond_to?(:body)
+        return "" if comment.nil?
+        comment.gsub(/^[ \t]*\*[ \t]{0,1}/, '')
+      end
+
+      def register_docstring(object, docstring = statement.comments, stmt = statement)
+        docstring = docstring.last if Array === docstring
+        docstring = clean_comment(docstring) if docstring
+        docstring.force_encoding('utf-8') if docstring
+
+        super(object, docstring, stmt)
+      end
+
+      def register_source(object, source = statement.source, type = parser.parser_type)
+        return unless object.is_a?(CodeObjects::PropertyObject)
+        object.source ||= source
+        object.source_type = type
+      end
+    end
+  end
+end

data/lib/yard-js/handlers/class_handler.rb

@@ -0,0 +1,43 @@
+require_relative 'base'
+
+module YARDJS
+  module Handlers
+    class ClassHandler < Base
+      handles AssignmentExpression
+      handles Property
+
+      process do
+        statement.comments ||= parser.extra_state.comments
+        handle_default_comments
+
+        if statement.is_a?(AssignmentExpression)
+          left, right = statement.left, statement.right
+        else
+          left, right = statement.key, statement.value
+        end
+
+        return unless right.is_a?(CallExpression) &&
+          right.callee.source =~ YARDJS.options.define_class_expression
+
+        obj = register YARD::CodeObjects::ClassObject.new(namespace, left.source)
+        obj.superclass = right.args.first.source if right.args.size > 1
+
+        defs = right.args.last.properties
+        parse_block(defs, :namespace => obj)
+      end
+    end
+
+    class UpdateClassHandler < Base
+      handles CallExpression
+
+      process do
+        return unless statement.callee.source =~
+          YARDJS.options.update_class_expression
+
+        ns = P(statement.args.first.source.gsub(/\.prototype/, ''))
+        ensure_loaded!(ns)
+        parse_block(statement.args.last.properties, :namespace => ns)
+      end
+    end
+  end
+end

data/lib/yard-js/handlers/comment_handler.rb

@@ -0,0 +1,33 @@
+require_relative 'base'
+
+module YARDJS
+  module Handlers
+    class CommentedStatementHandler < Base
+      handles CommentedStatement
+
+      process do
+        parser.extra_state.comments = statement.comments
+        parse_block(statement.statement)
+        parser.extra_state.comments = nil
+      end
+    end
+
+    class ExpressionStatementHandler < Base
+      handles ExpressionStatement
+      process { parse_block statement.expression }
+    end
+
+    class SequenceExpressionStatementHandler < Base
+      handles SequenceExpression
+      process { parse_block statement.expressions }
+    end
+
+    class CommentHandler < Base
+      handles Comment
+
+      process do
+        register_docstring(nil)
+      end
+    end
+  end
+end

data/lib/yard-js/handlers/constant_handler.rb

@@ -0,0 +1,50 @@
+require_relative 'base'
+
+module YARDJS
+  module Handlers
+    class ConstantHandler < Base
+      handles AssignmentExpression
+      handles Property
+
+      process do
+        if statement.is_a?(AssignmentExpression)
+          name, value = statement.left.source, statement.right
+        else
+          name, value = statement.key.val, statement.value
+        end
+
+        return if value.is_a?(FunctionExpression)
+        return if value.is_a?(ObjectExpression)
+        return if value.is_a?(CallExpression)
+
+        handle_default_comments
+
+        obj = register CodeObjects::PropertyObject.new(namespace, name)
+        if value.is_a?(Literal)
+          obj.property_type = :literal
+          if type = parse_type(value.val)
+            obj.docstring.add_tag(YARD::Tags::Tag.new(:return, '', [type]))
+          end
+        else
+          obj.property_type = :object
+        end
+
+        unless obj.has_tag?(:value)
+          obj.docstring.add_tag(YARD::Tags::Tag.new(:value, value.source))
+        end
+
+        unless obj.has_tag?(:static)
+          obj.docstring.add_tag(YARD::Tags::Tag.new(:static, ''))
+        end
+      end
+
+      def parse_type(type)
+        case type
+        when Node; type.class.to_s[/::([^:]+)$/, 1]
+        when FalseClass, TrueClass; 'Boolean'
+        when NilClass; 'null'
+        end
+      end
+    end
+  end
+end

data/lib/yard-js/handlers/instance_method_handler.rb

@@ -0,0 +1,26 @@
+require_relative 'base'
+
+module YARDJS
+  module Handlers
+    class InstanceMethodHandler < Base
+      handles Property
+
+      process do
+        return unless statement.value.is_a?(FunctionExpression)
+
+        handle_default_comments
+
+        name = statement.key.val
+        params = statement.value.params.list.map {|t| [t.val, nil]}
+
+        obj = register CodeObjects::PropertyObject.new(namespace, name)
+        obj.property_type = :function
+        obj.parameters = params
+        obj.signature = "#{name}(#{params.join(', ')})"
+        unless obj.has_tag?(:return)
+          obj.docstring.add_tag(YARD::Tags::Tag.new(:return, '', ['void']))
+        end
+      end
+    end
+  end
+end

data/lib/yard-js/handlers/mixin_handler.rb

@@ -0,0 +1,18 @@
+require_relative 'base'
+
+module YARDJS
+  module Handlers
+    class MixinHandler < Base
+      handles CallExpression
+
+      process do
+        return unless statement.callee.source =~ YARDJS.options.mixin_module_expression
+
+        obj = YARD::CodeObjects::ClassObject.new(:root, statement.args.first.source)
+        obj.instance_mixins.push(*statement.args[1..-1].map do |arg|
+          YARD::CodeObjects::ClassObject.new(:root, arg.source)
+        end)
+      end
+    end
+  end
+end

data/lib/yard-js/handlers/module_handler.rb

@@ -0,0 +1,33 @@
+require_relative 'base'
+
+module YARDJS
+  module Handlers
+    class ModuleHandler < Base
+      handles AssignmentExpression
+      handles VariableDeclaration
+      handles Property
+
+      process do
+        case statement
+        when VariableDeclaration
+          left = statement.declarations.first.id
+          right = statement.declarations.first.init
+        when AssignmentExpression
+          left = statement.left
+          right = statement.right
+        when Property
+          left = statement.key
+          right = statement.value
+        end
+
+        return unless ObjectExpression === right
+
+        statement.comments ||= parser.extra_state.comments
+        handle_default_comments
+
+        obj = register YARD::CodeObjects::ModuleObject.new(namespace, left.source)
+        parse_block(right.properties, :namespace => obj)
+      end
+    end
+  end
+end

data/lib/yard-js/parser.rb

@@ -0,0 +1,23 @@
+require_relative 'core_ext/yard'
+
+module YARDJS
+  module Parser
+    class JavaScriptParser < YARD::Parser::Base
+      attr_accessor :file, :source, :ast
+
+      def initialize(source, filename)
+        self.source = source
+        self.file = filename
+      end
+
+      def parse
+        self.ast = ParseJS.parse(source)
+        self
+      end
+
+      def enumerator
+        ast.elements
+      end
+    end
+  end
+end

data/lib/yard-js/plugin.rb

@@ -0,0 +1,23 @@
+require_relative 'core_ext/yard'
+require_relative 'code_objects'
+require_relative 'handlers'
+require_relative 'tags'
+require_relative 'parser'
+
+YARD::Parser::SourceParser.register_parser_type(:js, YARDJS::Parser::JavaScriptParser, ['js'])
+YARD::Handlers::Processor.register_handler_namespace(:js, YARDJS::Handlers)
+
+YARD::Templates::Engine.register_template_path(File.dirname(__FILE__) + '/../../templates')
+
+[:readonly, :writeonly, :static].each do |tag|
+  YARD::Tags::Library.define_tag(tag.to_s.capitalize, tag)
+end
+YARD::Tags::Library.define_tag 'Default Value', :default, :with_name
+YARD::Tags::Library.define_tag 'Default Value', :value
+YARD::Tags::Library.define_tag 'Constant', :constant
+YARD::Tags::Library.define_tag 'Context (<tt>this</tt>)', :context, :with_types
+YARD::Tags::Library.define_tag 'Callback', :callback, YARDJS::Tags::CallbackTag
+YARD::Tags::Library.visible_tags.unshift(:value, :context)
+
+YARD::Tags::Library.define_directive(:ignore, YARDJS::Tags::IgnoreDirective)
+YARD::Tags::Library.define_directive(:event, :with_title_and_text, YARDJS::Tags::EventDirective)