Class: RDoc::Context::Section

Inherits:
Object
  • Object
show all
Includes:
Generator::Markup, Text
Defined in:
lib/rdoc/context/section.rb,
lib/rdoc/generator/markup.rb

Overview

A section of documentation like:

# :section: The title
# The body

Sections can be referenced multiple times and will be collapsed into a single section.

Constant Summary collapse

MARSHAL_VERSION =

:nodoc:

0

Constants included from Text

Text::MARKUP_FORMAT, Text::TO_HTML_CHARACTERS

Instance Attribute Summary collapse

Attributes included from Text

#language

Instance Method Summary collapse

Methods included from Generator::Markup

#aref_to, #as_href, #cvs_url, #description, #formatter

Methods included from Text

encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #snippet, #strip_hashes, #strip_newlines, #strip_stars, #to_html, #wrap

Constructor Details

#initialize(parent, title, comment) ⇒ Section

Creates a new section with title and comment



40
41
42
43
44
45
46
47
 
# File 'lib/rdoc/context/section.rb', line 40

def initialize parent, title, comment
  @parent = parent
  @title = title ? title.strip : title

  @comments = []

  add_comment comment
end

Instance Attribute Details

#comment ⇒ Object (readonly)

Section comment



20
21
22
 
# File 'lib/rdoc/context/section.rb', line 20

def comment
  @comment
end

#comments ⇒ Object (readonly)

Section comments



25
26
27
 
# File 'lib/rdoc/context/section.rb', line 25

def comments
  @comments
end

#parent ⇒ Object (readonly)

Context this Section lives in



30
31
32
 
# File 'lib/rdoc/context/section.rb', line 30

def parent
  @parent
end

#title ⇒ Object (readonly)

Section title



35
36
37
 
# File 'lib/rdoc/context/section.rb', line 35

def title
  @title
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

Sections are equal when they have the same #title



52
53
54
 
# File 'lib/rdoc/context/section.rb', line 52

def == other
  self.class === other and @title == other.title
end

#add_comment(comment) ⇒ Object

Adds comment to this section



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/rdoc/context/section.rb', line 61

def add_comment comment
  comment = extract_comment comment

  return if comment.empty?

  case comment
  when RDoc::Comment then
    @comments << comment
  when RDoc::Markup::Document then
    @comments.concat comment.parts
  when Array then
    @comments.concat comment
  else
    raise TypeError, "unknown comment type: #{comment.inspect}"
  end
end

#aref ⇒ Object

Anchor reference for linking to this section



81
82
83
84
85
 
# File 'lib/rdoc/context/section.rb', line 81

def aref
  title = @title || '[untitled]'

  CGI.escape(title).gsub('%', '-').sub(/^-/, '')
end

#extract_comment(comment) ⇒ Object

Extracts the comment for this section from the original comment block. If the first line contains :section:, strip it and use the rest. Otherwise remove lines up to the line containing :section:, and look for those lines again at the end and remove them. This lets us write

# :section: The title
# The body



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
 
# File 'lib/rdoc/context/section.rb', line 96

def extract_comment comment
  case comment
  when Array then
    comment.map do |c|
      extract_comment c
    end
  when nil
    RDoc::Comment.new ''
  when RDoc::Comment then
    if comment.text =~ /^#[ \t]*:section:.*\n/ then
      start = $`
      rest = $'

      comment.text = if start.empty? then
                       rest
                     else
                       rest.sub(/#{start.chomp}\Z/, '')
                     end
    end

    comment
  when RDoc::Markup::Document then
    comment
  else
    raise TypeError, "unknown comment #{comment.inspect}"
  end
end

#hash ⇒ Object

:nodoc:



128
129
130
 
# File 'lib/rdoc/context/section.rb', line 128

def hash # :nodoc:
  @title.hash
end

#in_files ⇒ Object

The files comments in this section come from



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/rdoc/context/section.rb', line 135

def in_files
  return [] if @comments.empty?

  case @comments
  when Array then
    @comments.map do |comment|
      comment.file
    end
  when RDoc::Markup::Document then
    @comment.parts.map do |document|
      document.file
    end
  else
    raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
  end
end

#inspect ⇒ Object

:nodoc:



124
125
126
 
# File 'lib/rdoc/context/section.rb', line 124

def inspect # :nodoc:
  "#<%s:0x%x %p>" % [self.class, object_id, title]
end

#marshal_dump ⇒ Object

Serializes this Section. The title and parsed comment are saved, but not the section parent which must be restored manually.



156
157
158
159
160
161
162
 
# File 'lib/rdoc/context/section.rb', line 156

def marshal_dump
  [
    MARSHAL_VERSION,
    @title,
    parse,
  ]
end

#marshal_load(array) ⇒ Object

De-serializes this Section. The section parent must be restored manually.



167
168
169
170
171
172
 
# File 'lib/rdoc/context/section.rb', line 167

def marshal_load array
  @parent  = nil

  @title    = array[1]
  @comments = array[2]
end

#parse ⇒ Object

Parses comment_location into an RDoc::Markup::Document composed of multiple RDoc::Markup::Documents with their file set.



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/rdoc/context/section.rb', line 178

def parse
  case @comments
  when String then
    super
  when Array then
    docs = @comments.map do |comment, location|
      doc = super comment
      doc.file = location if location
      doc
    end

    RDoc::Markup::Document.new(*docs)
  when RDoc::Comment then
    doc = super @comments.text, comments.format
    doc.file = @comments.location
    doc
  when RDoc::Markup::Document then
    return @comments
  else
    raise ArgumentError, "unknown comment class #{comments.class}"
  end
end

#plain_html ⇒ Object

The section’s title, or ‘Top Section’ if the title is nil.

This is used by the table of contents template so the name is silly.



206
207
208
 
# File 'lib/rdoc/context/section.rb', line 206

def plain_html
  @title || 'Top Section'
end

#remove_comment(comment) ⇒ Object

Removes a comment from this section if it is from the same file as comment



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/rdoc/context/section.rb', line 214

def remove_comment comment
  return if @comments.empty?

  case @comments
  when Array then
    @comments.delete_if do |my_comment|
      my_comment.file == comment.file
    end
  when RDoc::Markup::Document then
    @comments.parts.delete_if do |document|
      document.file == comment.file.name
    end
  else
    raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
  end
end