Module: YARD::TomDoc

Defined in:
lib/yard-tomdoc.rb

Constant Summary collapse

NAME =

Distribution name of this program.

'yard-tomdoc'
TAGS =

Tags supported by YARD that Tomparse can handle.

%w{abstract attr attr_reader attr_writer attribute author deprecated note see since todo version}

Class Method Summary collapse

Class Method Details

.const_missing(const_name) ⇒ Object

When a constant is missing, see if it is a metadata entry. Metadata comes from the RubyGem, and fallsback to project index file.

Parameters:

  • name (Symbol) —

    constant name

Returns:

  • metadata value.



95
96
97
 
# File 'lib/yard-tomdoc.rb', line 95

def self.const_missing(name)
  metadata[name.to_s.downcase] || super(name)
end

.index ⇒ Hash

Metadata from the ‘yard-tomdoc.yml` or `.index` file.

Returns:

  • (Hash) —

    Returns metadata.



103
104
105
106
107
108
109
110
 
# File 'lib/yard-tomdoc.rb', line 103

def self.index
  @index ||= (
    require 'yaml'
    dir  = File.dirname(__FILE__)
    file = Dir[File.join(dir, "{#{NAME}.yml,../.index}")].first
    file ? YAML.load_file(file) : {}
  )
end

.yard_parse(yard, comment) ⇒ TomDoc

Parse comments with TomDoc and then provide YARD with results.

Parameters:

Returns:

  • (TomDoc) —

    Returns instance of TomDoc.



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/yard-tomdoc.rb', line 20

def self.yard_parse(yard, comment)
  tomdoc = TomParse.parse(comment)

  # TODO: TomParse should make the `strip` unecessary
  tomdoc.examples.each {|ex| yard.create_tag(:example, "\n" + ex.strip) }

  # TODO: how to figure-out class of argument ?
  tomdoc.arguments.each {|arg| yard.create_tag(:param, "#{arg.name} #{arg.description}") }

  tomdoc.arguments.each do |arg|
    arg.options.each do |opt|
      yard.create_tag(:option, "#{arg.name} #{opt.name} #{opt.description}")
    end
  end

  tomdoc.raises.each {|r| yard.create_tag(:raise, r.sub(/\ARaises\s+/, '')) }

  if tomdoc.returns.empty?
    if md = /\[(.*?)\]\s*\Z/.match(tomdoc.description)
      klass = md[1]
      yard.create_tag(:return, "[#{klass}]")
    end
  end

  tomdoc.returns.each do |r|
    if md = /\AReturn(s)?\ nothing(\.)?\Z/.match(r)
      yard.create_tag(:return, "[void]")
    elsif md = /\[(.*?)\]\Z/.match(r)
      klass = md[1]
      desc  = md.pre_match
      yard.create_tag(:return, "[#{klass}] #{desc}")
    elsif md = /\[(.*?)\]/.match(r)
      klass = md[1]
      desc  = r.sub("[#{md[1]}]", md[1])
      yard.create_tag(:return, "[#{klass}] #{desc}")
    elsif md = /\AReturns\s+([A-Z].*?)\s+/.match(r)
      klass = md[1]
      desc  = md.post_match
      yard.create_tag(:return, "[#{klass}] #{desc}")
    else
      desc = r.sub(/\AReturns\s+/, '')
      yard.create_tag(:return, desc)
    end
  end

  yard.create_tag(:yield, tomdoc.yields) if tomdoc.yields

  yard.create_tag(:deprecated, 'Do not use this in new code, and replace it when updating old code.') if tomdoc.deprecated?

  yard.create_tag(:api, 'public')  if tomdoc.public?
  yard.create_tag(:api, 'private') if tomdoc.internal?

  tomdoc.tags.each do |(label, desc)|
    tag = label.to_s.downcase
    if TAGS.include?(tag)
      yard.create_tag(tag.to_sym, desc.to_s)
    end
  end

  tomdoc
end