Class: TomDoc::TomDoc

Inherits:
Object
  • Object
show all
Defined in:
lib/tomdoc/tomdoc.rb

Overview

TODO: Instead of having TomDoc::TomDoc, lets consider renaming this

class TomDoc::Comment or something.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(text, options = {}) ⇒ TomDoc

Public: Initialize a TomDoc object.

text - The raw text of a method or class/module comment.

Returns new TomDoc instance.



46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/tomdoc/tomdoc.rb', line 46

def initialize(text, options={})
  @raw = text.to_s.strip

  @arguments        = []
  @examples         = []
  @returns          = []
  @raises           = []
  @signatures       = []
  @signature_fields = []

  parse unless @raw.empty?
end

Instance Attribute Details

#raw ⇒ Object

Returns the value of attribute raw.



39
40
41
 
# File 'lib/tomdoc/tomdoc.rb', line 39

def raw
  @raw
end

Class Method Details

.valid?(text) ⇒ Boolean

Validate given comment text.

Returns true if comment is valid, otherwise false.

Returns:

  • (Boolean) 


66
67
68
 
# File 'lib/tomdoc/tomdoc.rb', line 66

def self.valid?(text)
  new(text).valid?
end

Instance Method Details

#arguments ⇒ Object Also known as: args

Description of method or class/module.

Returns description String.



155
156
157
158
159
 
# File 'lib/tomdoc/tomdoc.rb', line 155

def arguments
  parsed {
    @arguments
  }
end

#deprecated? ⇒ Boolean

Check if method is deprecated.

Returns true if method is deprecated.

Returns:

  • (Boolean) 


237
238
239
240
241
 
# File 'lib/tomdoc/tomdoc.rb', line 237

def deprecated?
  parsed {
    @status == 'Deprecated'
  }
end

#description ⇒ Object

Description of method or class/module.

Returns description String.



146
147
148
149
150
 
# File 'lib/tomdoc/tomdoc.rb', line 146

def description
  parsed {
    @description
  }
end

#examples ⇒ Object

List of use examples of a method or class/module.

Returns String of examples.



165
166
167
168
169
 
# File 'lib/tomdoc/tomdoc.rb', line 165

def examples
  parsed {
    @examples
  }
end

#internal? ⇒ Boolean

Check if method is internal.

Returns true if method is internal.

Returns:

  • (Boolean) 


228
229
230
231
232
 
# File 'lib/tomdoc/tomdoc.rb', line 228

def internal?
  parsed {
    @status == 'Internal'
  }
end

#public? ⇒ Boolean

Check if method is public.

Returns true if method is public.

Returns:

  • (Boolean) 


219
220
221
222
223
 
# File 'lib/tomdoc/tomdoc.rb', line 219

def public?
  parsed {
    @status == 'Public'
  }
end

#raises ⇒ Object

A list of errors a method might raise.

Returns Array of method raises descriptions.



192
193
194
195
196
 
# File 'lib/tomdoc/tomdoc.rb', line 192

def raises
  parsed {
    @raises
  }
end

#returns ⇒ Object

The list of retrun values a method can return.

Returns Array of method return descriptions.



183
184
185
186
187
 
# File 'lib/tomdoc/tomdoc.rb', line 183

def returns
  parsed {
    @returns
  }
end

#sections ⇒ Object

List of comment sections. These are divided simply on “nn”.

Returns Array of comment sections.



137
138
139
140
141
 
# File 'lib/tomdoc/tomdoc.rb', line 137

def sections
  parsed {
    @sections
  }
end

#signature_fields ⇒ Object

A list of signature fields.

Returns Array of field definitions.



210
211
212
213
214
 
# File 'lib/tomdoc/tomdoc.rb', line 210

def signature_fields
  parsed {
    @signature_fields
  }
end

#signatures ⇒ Object

A list of alternate method signatures.

Returns Array of signatures.



201
202
203
204
205
 
# File 'lib/tomdoc/tomdoc.rb', line 201

def signatures
  parsed {
    @signatures 
  }
end

#to_s ⇒ Object 



59
60
61
 
# File 'lib/tomdoc/tomdoc.rb', line 59

def to_s
  @raw
end

#tomdoc ⇒ Object

The raw comment text cleaned-up and ready for section parsing.

Returns cleaned-up comment String.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/tomdoc/tomdoc.rb', line 98

def tomdoc
  lines = raw.split("\n")

  # remove remark symbol
  if lines.all?{ |line| /^\s*#/ =~ line }   
    lines = lines.map do |line|
      line =~ /^(\s*#)/ ? line.sub($1, '') : nil
    end
  end

  # for some reason the first line is coming in without indention
  # regardless, so we temporary remove it
  first = lines.shift

  # remove indention
  spaces = lines.map do |line|
    next if line.strip.empty?
    md = /^(\s*)/.match(line)
    md ? md[1].size : nil
  end.compact

  space = spaces.min || 0
  lines = lines.map do |line|
    if line.empty?
      line.strip
    else
      line[space..-1]
    end
  end

  # put first line back
  lines.unshift(first.sub(/^\s*/,''))

  lines.compact.join("\n")
end

#valid? ⇒ Boolean

Validate raw comment.

Returns true if comment is valid, otherwise false.

Returns:

  • (Boolean) 


73
74
75
76
77
 
# File 'lib/tomdoc/tomdoc.rb', line 73

def valid?
  return false if !raw.include?('Returns')
  return false if sections.size < 2
  true
end

#validate ⇒ Object

Validate raw comment.

Returns true if comment is valid. Raises InvalidTomDoc if comment is not valid.



83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/tomdoc/tomdoc.rb', line 83

def validate
  if !raw.include?('Returns')
    raise InvalidTomDoc.new("No `Returns' statement.")
  end

  if sections.size < 2
    raise InvalidTomDoc.new("No description section found.")
  end

  true
end

#yields ⇒ Object

Description of a methods yield procedure.

Returns String decription of yield procedure.



174
175
176
177
178
 
# File 'lib/tomdoc/tomdoc.rb', line 174

def yields
  parsed {
    @yields
  }
end