Class: RDoc::Context::Section

Inherits:
Object
  • Object
show all
Includes:
Generator::Markup, Text
Defined in:
lib/rdoc/code_object/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::SPACE_SEPARATED_LETTER_CLASS, Text::TO_HTML_CHARACTERS

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Generator::Markup

#aref_to, #as_href, #canonical_url, #cvs_url, #formatter

Methods included from Text

decode_legacy_label, encode_fallback, expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, to_anchor, #to_html, #to_html_characters, #wrap

Constructor Details

#initialize(parent, title, comment, store = nil) ⇒ Section

Creates a new section with title and comment



43
44
45
46
47
48
49
50
51
 
# File 'lib/rdoc/code_object/context/section.rb', line 43

def initialize(parent, title, comment, store = nil)
  @parent = parent
  @title = title ? title.strip : title
  @store = store

  @comments = []

  add_comment comment
end

Instance Attribute Details

#comments ⇒ Object (readonly)

Section comments



23
24
25
 
# File 'lib/rdoc/code_object/context/section.rb', line 23

def comments
  @comments
end

#parent ⇒ Object (readonly)

Context this Section lives in



28
29
30
 
# File 'lib/rdoc/code_object/context/section.rb', line 28

def parent
  @parent
end

#store ⇒ Object (readonly)

The RDoc::Store for this object.



38
39
40
 
# File 'lib/rdoc/code_object/context/section.rb', line 38

def store
  @store
end

#title ⇒ Object (readonly)

Section title



33
34
35
 
# File 'lib/rdoc/code_object/context/section.rb', line 33

def title
  @title
end

Instance Method Details

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

Sections are equal when they have the same #title



56
57
58
 
# File 'lib/rdoc/code_object/context/section.rb', line 56

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

#add_comment(comment) ⇒ Object

Adds comment to this section



65
66
67
68
69
70
71
 
# File 'lib/rdoc/code_object/context/section.rb', line 65

def add_comment(comment)
  comments = Array(comment)
  comments.each do |c|
    extracted_comment = extract_comment(c)
    @comments << extracted_comment unless extracted_comment.empty?
  end
end

#aref ⇒ Object

Anchor reference for linking to this section using GitHub-style format.

Examples:

"Section"     -> "section"
"One Two"     -> "one-two"
"[untitled]"  -> "untitled"



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

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

  RDoc::Text.to_anchor(title)
end

#comment ⇒ Object

Section comment



189
190
191
192
 
# File 'lib/rdoc/code_object/context/section.rb', line 189

def comment
  return nil if @comments.empty?
  RDoc::Comment.from_document(to_document)
end

#description ⇒ Object 



194
195
196
197
 
# File 'lib/rdoc/code_object/context/section.rb', line 194

def description
  return '' if @comments.empty?
  markup comment
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



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/rdoc/code_object/context/section.rb', line 110

def extract_comment(comment)
  case comment
  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
  else
    raise TypeError, "unknown comment #{comment.inspect}"
  end
end

#hash ⇒ Object

:nodoc:



136
137
138
 
# File 'lib/rdoc/code_object/context/section.rb', line 136

def hash # :nodoc:
  @title.hash
end

#in_files ⇒ Object

The files comments in this section come from



143
144
145
 
# File 'lib/rdoc/code_object/context/section.rb', line 143

def in_files
  @comments.map(&:file)
end

#inspect ⇒ Object

:nodoc:



132
133
134
 
# File 'lib/rdoc/code_object/context/section.rb', line 132

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

#language ⇒ Object 



199
200
201
 
# File 'lib/rdoc/code_object/context/section.rb', line 199

def language
  @comments.first&.language
end

#legacy_aref ⇒ Object

Legacy anchor reference for backward compatibility.

Examples:

"Section"     -> "section"
"One Two"     -> "one+two"
"[untitled]"  -> "5Buntitled-5D"



95
96
97
98
99
 
# File 'lib/rdoc/code_object/context/section.rb', line 95

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

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

#marshal_dump ⇒ Object

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



151
152
153
154
155
156
157
 
# File 'lib/rdoc/code_object/context/section.rb', line 151

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

#marshal_load(array) ⇒ Object

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



162
163
164
165
166
167
 
# File 'lib/rdoc/code_object/context/section.rb', line 162

def marshal_load(array)
  @parent  = nil

  @title    = array[1]
  @comments = array[2].parts.map { |doc| RDoc::Comment.from_document(doc) }
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.



182
183
184
 
# File 'lib/rdoc/code_object/context/section.rb', line 182

def plain_html
  @title || 'Top Section'
end

#remove_comment(target_comment) ⇒ Object

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



207
208
209
210
211
 
# File 'lib/rdoc/code_object/context/section.rb', line 207

def remove_comment(target_comment)
  @comments.delete_if do |stored_comment|
    stored_comment.file == target_comment.file
  end
end

#to_document ⇒ Object

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



173
174
175
 
# File 'lib/rdoc/code_object/context/section.rb', line 173

def to_document
  RDoc::Markup::Document.new(*@comments.map(&:parse))
end