Class: Rain::Doc

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

Overview

used each time a file needs to be parsed. contains all documentation parts in the file as well as functionality to read through file contents line-by-line.

Constant Summary collapse

@@open_response = 
nil
@@open_response_id = 
nil
@@open_param = 
nil
@@open_param_type = 
nil
@@open_param_default = 
nil
@@log_lines = 
false

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file_name, file_contents, log_lines = false) ⇒ Doc

sets up the doc using the file name and contents as a basis.



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
 
# File 'lib/doc.rb', line 24

def initialize(file_name, file_contents, log_lines = false)

  # set up basic options and defaults
  self.file_name = file_name
  self.file_contents = file_contents
  self.file_ext = File.extname(file_name)
  self.parts = []
  self.lines = 0
  @@log_lines = log_lines

  # set the doc type based on extension
  case self.file_ext
  when '.rb'
    self.type = :RUBY
  when '.md', '.txt', '.markdown', '.mdown'
    self.type = :MARKDOWN
  end

  # set parser with file type
  self.parser = Rain::Parser.new(self.type)

  # set the default title to the proper-case file name
  # without the extension and underscores/dashes
  self.title = self.file_name.sub(self.file_ext, '')
  self.title.gsub!(/_|-/, ' ')

  # very simple proper-caser
  self.title.gsub!(/\w+/) { |word| word.capitalize }
end

Instance Attribute Details

#current_part ⇒ Object

Returns the value of attribute current_part.



12
13
14
 
# File 'lib/doc.rb', line 12

def current_part
  @current_part
end

#file_contents ⇒ Object

Returns the value of attribute file_contents.



12
13
14
 
# File 'lib/doc.rb', line 12

def file_contents
  @file_contents
end

#file_ext ⇒ Object

Returns the value of attribute file_ext.



12
13
14
 
# File 'lib/doc.rb', line 12

def file_ext
  @file_ext
end

#file_name ⇒ Object

Returns the value of attribute file_name.



12
13
14
 
# File 'lib/doc.rb', line 12

def file_name
  @file_name
end

#lines ⇒ Object

Returns the value of attribute lines.



12
13
14
 
# File 'lib/doc.rb', line 12

def lines
  @lines
end

#parser ⇒ Object

Returns the value of attribute parser.



12
13
14
 
# File 'lib/doc.rb', line 12

def parser
  @parser
end

#parts ⇒ Object

Returns the value of attribute parts.



12
13
14
 
# File 'lib/doc.rb', line 12

def parts
  @parts
end

#title ⇒ Object

Returns the value of attribute title.



12
13
14
 
# File 'lib/doc.rb', line 12

def title
  @title
end

#type ⇒ Object

Returns the value of attribute type.



12
13
14
 
# File 'lib/doc.rb', line 12

def type
  @type
end

Instance Method Details

#new_part ⇒ Object

adds the current part to the parts array then sets a new current part up. a part is just a completed DocPart from a section of comments. for markdown files there will only be one doc part.



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

def new_part
  self.parts << self.current_part if !self.current_part.nil?
  self.current_part = Rain::DocPart.new
end

#parse ⇒ Object

parses the file by looping through all of the lines. defers to parser functionality to figure out if the current line is a tag and needs to be parsed into the docpart.



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
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
133
134
135
136
137
138
139
140
 
# File 'lib/doc.rb', line 67

def parse
  self.new_part
  self.file_contents.each_line do |line|

    # parse the current line
    result = self.parser.parse(line)

    # if there is no documentation for the result,
    # create a new part and then set the current part to nil.
    if result.nil?
      self.new_part
      self.current_part = nil
      next
    else

      # if new doc block is found with the current part == nil,
      # create a new part
      self.new_part if self.current_part.nil?
    end
    
    # log the result if the logger is enabled
    Logger.new(STDOUT).info(result) if @@log_lines

    # figure out what to do based on the result type
    case result[:tag]
    when :title
      self.title = result[:title]
    when :route
      self.current_part.set_route(result[:route])
    when :method
      self.current_part.set_method(result[:method])
    when :response

      # open the current response tag using the code as a key
      if result[:open]
        @@open_response = result[:code]
        @@open_response_id = result[:id]
      else
        @@open_response = nil
      end
    when :param

      # open the current param tag using the name as the key
      if result[:open]
        @@open_param = result[:name]
        @@open_param_type = result[:type]
        @@open_param_default = result[:default]
      else
        @@open_param = nil
      end
    when :doc

      # figure out if the doc needs to be added to an
      # open response or param tag
      if !@@open_response.nil?
        self.current_part.append_response(@@open_response.to_i, @@open_response_id, result[:text])
      elsif !@@open_param.nil?
        self.current_part.append_param(@@open_param, result[:text], @@open_param_type, @@open_param_default)
      else
        self.current_part.append_doc(result[:text])
      end
    end

    self.lines += 1
  end

  # add the part and create a new one
  self.new_part

  # remove any empty parts (for ruby docs)
  if self.type == :RUBY
    self.parts = self.parts.select{ |part| part.route != "//" }
  end
end

#to_hash ⇒ Object 



142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/doc.rb', line 142

def to_hash
  return {
    file_name: self.file_name,
    file_contents: self.file_contents,
    file_ext: self.file_ext,
    title: self.title,
    lines: self.lines,
    parts: self.parts.map { |part| part.to_hash },
    type: self.type.to_s
  }
end