yard-go 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ad1b6df43092cbf0ade8457bc09cd7eaa0c4a9ee
+  data.tar.gz: e15019dbc2d1bee24731016ec03f3606f48e7c97
+SHA512:
+  metadata.gz: 27ce96455c464b3bf3867bcf79bc9db023669799920e0824915050a7dd2b0421190e1e9fed322948de7689d088d79d7e6a1186535a869dd72abe43e5b3b13837
+  data.tar.gz: f382bdeb474bc40b1f65c8eafa50f1763704c97466e18a32db84187627ea42c4430b417edd364a76e77b17df8c8f0a2a70b2f9469bbed97715e812a1128d542e

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Loren Segal
+
+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,5 @@
+# YARD for Go
+
+A [YARD][yard] plugin that adds support for documenting Go source programs.
+
+[yard]: http://yardoc.org

data/lib/yard-go.rb

@@ -0,0 +1,14 @@
+require 'yard'
+
+require_relative './yard-go/code_objects'
+require_relative './yard-go/extensions'
+require_relative './yard-go/handlers'
+require_relative './yard-go/helpers'
+require_relative './yard-go/parser'
+require_relative './yard-go/version'
+
+YARD::Templates::Engine.register_template_path(File.dirname(__FILE__) + '/../templates')
+YARD::Parser::SourceParser.register_parser_type(:go, YARDGo::Parser::Go, 'go')
+YARD::Handlers::Processor.register_handler_namespace(:go, YARDGo::Handlers)
+YARD::Tags::Library.visible_tags -= [:return]
+YARD::Tags::Library.define_tag "Read-only", :readonly

data/lib/yard-go/code_objects.rb

@@ -0,0 +1,86 @@
+module YARDGo
+  module CodeObjects
+    class PackageObject < YARD::CodeObjects::NamespaceObject
+      def sep; '/' end
+      def type; :package end
+      def source_type; :go end
+      def title; name.to_s end
+
+      def full_path
+        File.join(parent.full_path, name.to_s)
+      end
+
+      def inheritance_tree(*args) [self] end
+    end
+
+    class StructObject < YARD::CodeObjects::NamespaceObject
+      def sep; '.' end
+      def type; :struct end
+      def scope; :instance end
+      def title; namespace.title + "." + name.to_s end
+      def source_type; :go end
+
+      def inheritance_tree(include_mods = false)
+        list = (include_mods ? mixins(:instance) : [])
+        [self] + list.map do |m|
+          next m if m == self
+          next m unless m.respond_to?(:inheritance_tree)
+          m.inheritance_tree(include_mods)
+        end.flatten.uniq
+      end
+
+      def implemented_interfaces
+        YARD::Registry.all(:interface).select {|i| implements?(i) }
+      end
+
+      def implements?(interface)
+        interface.implemented_by?(self)
+      end
+    end
+
+    class BareStructObject < StructObject
+      def sep; '.' end
+      def type; :bare_struct end
+      def source_type; :go end
+    end
+
+    class FuncObject < YARD::CodeObjects::MethodObject
+      def sep; '.' end
+      def name(str = false) str ? super(false).to_s : super(false) end
+      def type; :method end
+      def title; parent.title + "." + name.to_s + "()" end
+      def scope_name; has_tag?(:abstract) ? "Interface Method" : (scope == :class ? "Function" : "Method") end
+      def source_type; :go end
+    end
+
+    class FieldObject < YARD::CodeObjects::Base
+      def sep; '::' end
+      def type; :field end
+      def title; namespace.title + "." + name.to_s end
+      def source_type; :go end
+
+      attr_accessor :field_type, :go_tags
+    end
+
+    class InterfaceObject < StructObject
+      def sep; '.' end
+      def type; :interface end
+      def source_type; :go end
+
+      def implemented_by?(struct)
+        m = struct.children.select {|t| t.type == :method && t.scope == :instance }.map(&:name)
+        children.select {|t| t.type == :method && t.scope == :instance }.all? {|t| m.include?(t.name) }
+      end
+
+      def implementing_structs
+        YARD::Registry.all(:struct).select {|s| implemented_by?(s) }
+      end
+    end
+
+    class ConstantObject < YARD::CodeObjects::ConstantObject
+      def sep; '.' end
+      def type; :constant end
+      def source_type; :go end
+    end
+  end
+end

data/lib/yard-go/extensions.rb

@@ -0,0 +1,64 @@
+require 'strscan'
+
+class YARD::CodeObjects::RootObject
+  def full_path
+    File.relative_path(ENV["GOPATH"] + "/src", Dir.pwd)
+  end
+end
+
+class YARD::CLI::Yardoc
+  def all_objects
+    YARD::Registry.all(:root, :package, :struct, :interface)
+  end
+end
+
+class YARD::CLI::Stats
+  undef stats_for_modules
+  undef stats_for_classes
+
+  def stats_for_packages
+    output "Packages", *type_statistics(:package)
+  end
+
+  def stats_for_structs
+    struct_stats = type_statistics(:struct)
+    bstruct_stats = type_statistics(:bare_struct)
+    stats = struct_stats.zip(bstruct_stats).map {|o| o.reduce(:+) }
+    output "Structs", *stats
+  end
+
+  def stats_for_interfaces
+    output "Interfaces", *type_statistics(:interface)
+  end
+
+  def stats_for_fields
+    output "Fields", *type_statistics(:field)
+  end
+end
+
+module YARD::Templates::Helpers::HtmlSyntaxHighlightHelper
+  MATCHES = {
+    "hljs-keyword" => %r{\b(?:break|default|func|interface|select|case|defer|go|map|struct|chan|else|goto|package|switch|const|fallthrough|if|range|type|continue|for|import|return|var)\b},
+    "hljs-constant" => %r{\b(nil|false|true|error|string|int64|int|int32|float|float32|float64|bool)\b},
+    "hljs-string" => %r{"(?:[^\\"]|\\.)*"|`.+?`},
+    "hljs-comment" => %r{\/\/.+},
+  }
+
+  def html_syntax_highlight_go(source)
+    s = StringScanner.new(source, true)
+
+    highlighted = ""
+    until s.eos?
+      found = false
+      MATCHES.each do |klass, re|
+        if s.scan(re)
+          found = true
+          highlighted << "<span class=\"#{klass}\">#{s[0]}</span>"
+        end
+      end
+      highlighted << s.getch unless found
+    end
+
+    '<div class="hljs">' + highlighted + '</div>'
+  end
+end

data/lib/yard-go/handlers.rb

@@ -0,0 +1,186 @@
+module YARDGo
+  module Handlers
+    class Base < YARD::Handlers::Base
+      include YARDGo::CodeObjects
+
+      def self.handles?(node)
+        handlers.any? do |h|
+          (node.name.nil? || node.name[0] == node.name[0].upcase) &&
+          node.type == h
+        end
+      end
+
+      def parse_block(inner_node, opts = {})
+        push_state(opts) { parser.process([inner_node].flatten) }
+      end
+
+      def call_params; [] end
+      def caller_method; nil end
+
+      def pkg
+        return @pkg if @pkg
+        pkg = :root
+        path = File.dirname(File.relative_path(Dir.pwd, parser.file))
+        parts = path.split('/')
+        while parts.size > 0
+          pkg = PackageObject.new(pkg, parts.shift)
+          pkg.add_file(path) unless pkg.file
+        end
+
+        @pkg = pkg
+      end
+
+      def test_file?
+        parser.file =~ /_test\.go$/
+      end
+    end
+
+    class StructHandler < Base
+      handles :struct
+
+      process do
+        return if test_file?
+
+        ns = if regular_meths.size > 0 # it's a "class"
+          register StructObject.new(pkg, statement.name)
+        else # bare struct
+          register BareStructObject.new(pkg, statement.name)
+        end
+
+        parse_block(statement.meths, namespace: ns)
+        parse_block(statement.fields, namespace: ns)
+      end
+
+      def regular_meths
+        statement.meths.reject {|s| s.name =~ /^(Go)?String$/ }
+      end
+    end
+
+    class InterfaceHandler < Base
+      handles :interface
+
+      process do
+        return if test_file?
+
+        obj = register InterfaceObject.new(pkg, statement.name)
+        parse_block(statement.fields, namespace: obj)
+      end
+    end
+
+    class FunctionHandler < Base
+      handles :function
+      handles :method
+
+      process do
+        return parse_example if test_file?
+
+        scope = statement.type == :function ? :class : :instance
+        ns = statement.type == :function ? pkg : namespace
+        ctor_fn = false
+
+        if scope == :class && statement.ret =~ /^\s*\*([A-Z]\w*)\s*$/
+          ctor_fn = true
+          ns = StructObject.new(pkg, $1)
+        end
+
+        obj = register FuncObject.new(ns, statement.name, scope)
+        obj.signature = "func #{statement.name}#{statement.args}"
+        obj.parameters = statement.args.split(/,/).map{|a| [a, nil] }
+
+        if statement.ret && statement.ret.strip != ""
+          obj.add_tag YARD::Tags::Tag.new(:return, '', [statement.ret])
+        end
+
+        if ctor_fn
+          obj.group = "Constructor Functions"
+        end
+      end
+
+      private
+
+      def parse_example
+        return unless statement.name =~ /^Example(.+)/
+        parts = $1.split("_")
+
+        ns = pkg
+        if parts.size > 1
+          ns = P(pkg, parts.first)
+          ensure_loaded! ns
+        end
+
+        meth = P(ns, "." + parts.last)
+        ensure_loaded! meth
+
+        src = statement.source.split("\n")[1...-1].map {|l| l.sub(/^\t/, "") }.join("\n").sub(/\n^\/\/ Output:.+\Z/m, "")
+        meth.add_tag YARD::Tags::Tag.new(:example, src, nil, "")
+      end
+    end
+
+    class FieldFnHandler < Base
+      handles :fieldfn
+
+      process do
+        return if test_file?
+
+        obj = register FuncObject.new(namespace, statement.name, :instance)
+        obj.signature = "func #{statement.name}(#{statement.args})"
+        obj.parameters = statement.args.split(/,/).map{|a| [a, nil] }
+        if statement.ret && statement.ret.strip != ""
+          obj.add_tag YARD::Tags::Tag.new(:return, '', [statement.ret])
+        end
+        obj.add_tag YARD::Tags::Tag.new(:abstract, '')
+      end
+
+    end
+
+    class FieldHandler < Base
+      handles :field
+
+      process do
+        return if test_file?
+
+        obj = register FieldObject.new(namespace, statement.name, :instance)
+        obj.add_tag YARD::Tags::Tag.new(:return, '', [statement.field_type])
+        obj.add_tag YARD::Tags::Tag.new(:gotags, statement.tags)
+      end
+    end
+
+    class PackageHandler < Base
+      handles :package
+
+      process do
+        return if test_file?
+        register_docstring pkg if statement.comments.size > 0
+      end
+    end
+
+    class ConstantHandler < Base
+      handles :const
+      handles :var
+
+      process do
+        return if test_file?
+
+        obj = register ConstantObject.new(pkg, statement.name)
+
+        lhs = statement.name
+        lhs += " " + statement.vartype if statement.vartype
+        obj.source = "#{statement.type} #{lhs} = #{statement.value}"
+        obj.value = statement.value
+        obj.add_tag YARD::Tags::Tag.new(:constant_type, statement.type.to_s)
+        obj.add_tag YARD::Tags::Tag.new(:return, '', [statement.vartype])
+        obj.add_tag YARD::Tags::Tag.new(:readonly, '') if statement.type == :const
+      end
+    end
+
+    class CompositionHandler < Base
+      handles :composition
+
+      process do
+        return if test_file?
+
+        namespace.mixins(:instance) << P(namespace, statement.path)
+      end
+    end
+  end
+end

data/lib/yard-go/helpers.rb

@@ -0,0 +1,94 @@
+module LinkHelpers
+  include YARDGo::CodeObjects
+
+  def link_object(obj, title = nil, anchor = nil, relative = true)
+    case obj
+    when BareStructObject
+      origobj = object
+      @object = object.namespace if BareStructObject === object
+      link = super(obj.namespace, title || obj.name, anchor_for(obj), true)
+      @object = origobj
+      link
+    else
+      super(obj, title, anchor, relative)
+    end
+  end
+
+  def anchor_for(obj)
+    case obj
+    when BareStructObject
+      "type-#{obj.name}"
+    else
+      super(obj)
+    end
+  end
+
+  def signature(obj, link = true, show_extras = true, full_attr_name = true)
+    case obj
+    when FieldObject
+      ret = obj.has_tag?(:return) ? obj.tag(:return).types.join(", ") : ""
+      if link
+        return linkify obj, "<strong>#{obj.name}</strong> #{ret}"
+      else
+        return "<strong>#{obj.name}</strong> #{link_types(ret)}"
+      end
+    when BareStructObject, StructObject, InterfaceObject
+      if link
+        return linkify obj, "<strong>#{obj.name}</strong>"
+      else
+        return "<strong>#{obj.name}</strong> struct"
+      end
+    when FuncObject
+      src = obj.source.split(/\n/).first.sub(/\{\s*$/, '').sub(/(<a\s[^>]+>|\b)#{obj.name.to_s}(<\/a>)?\(/, "<strong>#{obj.name}</strong>(")
+      src = link_types(src) unless link
+      src
+
+      if link
+        return linkify obj, src
+      else
+        return src
+      end
+    end
+
+    super(obj, link, show_extras, full_attr_name)
+  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
+
+    val = ""
+    if meth.tag(:return) && meth.tag(:return).types
+      val = meth.tag(:return).types.join(", ")
+    end
+
+    link ? link_types(val) : val
+  end
+
+  def link_types(text)
+    text.gsub(/\b(?:[a-z]\w*\.)?[A-Z]\w*:?/) do |m|
+      if m[-1] == ":"
+        m
+      else
+        link_object YARD::Registry.resolve(object, m), m
+      end
+    end
+  end
+
+  def html_syntax_highlight(source, type = nil)
+    super(source, type || :go)
+  end
+
+  def format_object_title(obj)
+    case obj
+    when YARD::CodeObjects::RootObject
+      "Package: #{obj.full_path.split('/').last}"
+    else
+      super(obj)
+    end
+  end
+end
+
+YARD::Templates::Helpers::HtmlHelper.send(:prepend, LinkHelpers)