Class: JsDuck::DocFormatter

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

Overview

Formats doc-comments

Instance Method Summary collapse

Constructor Details

#initialize(relations = {}, opts = {}) ⇒ DocFormatter

Creates a formatter configured with options originating from command line. For the actual effect of the options see Inline::* classes.



19
20
21
22
23
24
25
26
27
28
 
# File 'lib/jsduck/doc_formatter.rb', line 19

def initialize(relations={}, opts={})
  @opts = opts
  @link_renderer = Inline::LinkRenderer.new(relations, opts)
  @inline_link = Inline::Link.new(@link_renderer)
  @auto_link = Inline::AutoLink.new(@link_renderer)
  @inline_img = Inline::Img.new(opts)
  @inline_video = Inline::Video.new(opts)
  @inline_example = Inline::Example.new(opts)
  @doc_context = {}
end

Instance Method Details

#class_context=(cls) ⇒ Object

Sets up instance to work in context of particular class, so that when #blah is encountered it knows that Context#blah is meant.



41
42
43
44
 
# File 'lib/jsduck/doc_formatter.rb', line 41

def class_context=(cls)
  @inline_link.class_context = cls
  @auto_link.class_context = cls
end

#doc_context ⇒ Object

Returns the current documentation context



57
58
59
 
# File 'lib/jsduck/doc_formatter.rb', line 57

def doc_context
  @doc_context
end

#doc_context=(doc) ⇒ Object

Sets up instance to work in context of particular doc object. Used for error reporting.



48
49
50
51
52
53
54
 
# File 'lib/jsduck/doc_formatter.rb', line 48

def doc_context=(doc)
  @doc_context = doc
  @inline_video.doc_context = doc
  @inline_link.doc_context = doc
  @auto_link.doc_context = doc
  @inline_img.doc_context = doc
end

#format(input) ⇒ Object

Formats doc-comment for placement into HTML. Renders it with Markdown-formatter and replaces @link-s.



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/jsduck/doc_formatter.rb', line 63

def format(input)
  # In ExtJS source "<pre>" is often at the end of paragraph, not
  # on its own line.  But in that case RDiscount doesn't recognize
  # it as the beginning of <pre>-block and goes on parsing it as
  # normal Markdown, which often causes nested <pre>-blocks.
  #
  # To prevent this, we always add extra newline before <pre>.
  input.gsub!(/([^\n])<pre>/, "\\1\n<pre>")

  # But we remove trailing newline after <pre> to prevent
  # code-blocks beginning with empty line.
  input.gsub!(/<pre>(<code>)?\n?/, "<pre>\\1")

  replace(RDiscount.new(input).to_html)
end

#images ⇒ Object 



34
35
36
 
# File 'lib/jsduck/doc_formatter.rb', line 34

def images
  @inline_img.images
end

#images=(images) ⇒ Object

Accessors to the images attribute of Inline::Img



31
32
33
 
# File 'lib/jsduck/doc_formatter.rb', line 31

def images=(images)
  @inline_img.images = images
end

#link(cls, member, anchor_text, type = nil, static = nil) ⇒ Object

Creates a link based on the link template.



136
137
138
 
# File 'lib/jsduck/doc_formatter.rb', line 136

def link(cls, member, anchor_text, type=nil, static=nil)
  @link_renderer.link(cls, member, anchor_text, type, static)
end

#replace(input) ⇒ Object

Replaces @link and @img tags, auto-generates links for recognized classnames.

Replaces Class#member link text in given string with HTML from @link_tpl.

Replaces path/to/image.jpg Alt text with HTML from @img_tpl.

Adds ‘inline-example’ class to code examples beginning with @example.

Additionally replaces strings recognized as ClassNames or #members with links to these classes or members. So one doesn’t even need to use the @link tag to create a link.



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
 
# File 'lib/jsduck/doc_formatter.rb', line 92

def replace(input)
  s = StringScanner.new(input)
  out = ""

  # Keep track of open HTML tags. We're not auto-detecting class
  # names when inside <a>. Also we want to close down the unclosed
  # tags.
  tags = HtmlStack.new(@opts[:ignore_html] || {}, @doc_context)

  while !s.eos? do
    if substitute = @inline_link.replace(s)
      out += substitute
    elsif substitute = @inline_img.replace(s)
      out += substitute
    elsif substitute = @inline_video.replace(s)
      out += substitute
    elsif s.check(/[{]/)
      # There might still be "{" that doesn't begin {@link} or {@img} - ignore it
      out += s.scan(/[{]/)
    elsif substitute = @inline_example.replace(s)
      tags.push_tag("pre")
      tags.push_tag("code")
      out += substitute
    elsif s.check(/<\w/)
      # Open HTML tag
      out += tags.open(s)
    elsif s.check(/<\/\w+>/)
      # Close HTML tag
      out += tags.close(s)
    elsif s.check(/</)
      # Ignore plain '<' char.
      out += s.scan(/</)
    else
      # Replace class names in the following text up to next "<" or "{"
      # but only when we're not inside <a>...</a>
      text = s.scan(/[^{<]+/)
      out += tags.open?("a") ? text : @auto_link.replace(text)
    end
  end

  out
end