Class: Decode::Documentation

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

Overview

Structured access to a set of comment lines.

Constant Summary collapse

DESCRIPTION = 
/\A\s*([^@\s].*)?\z/
ATTRIBUTE = 
/\A\s*@(?<name>.*?)\s+(?<value>.*?)\z/
PARAMETER = 
/\A\s*@param\s+(?<name>.*?)\s+\[(?<type>.*?)\]\s+(?<details>.*?)\z/

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(comments, language = nil) ⇒ Documentation

Initialize the documentation with an array of comments, within a specific language.

Parameters:

  • comments (Array(String)) —

    An array of comment lines.

  • language (Language) (defaults to: nil) —

    The language in which the comments were extracted.



28
29
30
31
 
# File 'lib/decode/documentation.rb', line 28

def initialize(comments, language = nil)
  @comments = comments
  @language = language
end

Instance Attribute Details

#language ⇒ Object (readonly)

The language in which the documentation was extracted from.



34
35
36
 
# File 'lib/decode/documentation.rb', line 34

def language
  @language
end

Instance Method Details

#attributes {|String| ... } ⇒ Enumerable

The attribute lines of the comment block. e.g. ‘@return [String]`.

Yields:

  • (String)

Returns:

  • (Enumerable) 


73
74
75
76
77
78
79
80
81
 
# File 'lib/decode/documentation.rb', line 73

def attributes
  return to_enum(:attributes) unless block_given?
  
  @comments.each do |comment|
    if match = comment.match(ATTRIBUTE)
      yield match
    end
  end
end

#description {|String| ... } ⇒ Enumerable

The text-only lines of the comment block.

Yields:

  • (String)

Returns:

  • (Enumerable) 


42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/decode/documentation.rb', line 42

def description
  return to_enum(:description) unless block_given?
  
  # We track empty lines and only yield a single empty line when there is another line of text:
  gap = false
  
  @comments.each do |comment|
    if match = comment.match(DESCRIPTION)
      if match[1]
        if gap
          yield ""
          gap = false
        end
        
        yield match[1]
      else
        gap = true
      end
    else
      break
    end
  end
end

#parameters {|String| ... } ⇒ Enumerable

The parameter lines of the comment block. e.g. ‘@param value [String] The value.`

Yields:

  • (String)

Returns:

  • (Enumerable) 


90
91
92
93
94
95
96
97
98
 
# File 'lib/decode/documentation.rb', line 90

def parameters
  return to_enum(:parameters) unless block_given?
  
  @comments.each do |comment|
    if match = comment.match(PARAMETER)
      yield match
    end
  end
end