Class: JsDuck::Format::Doc

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

Overview

Formats doc-comments

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

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

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



21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/jsduck/format/doc.rb', line 21

def initialize(relations={}, opts={})
  @relations = relations
  @opts = opts
  @subproperties = Format::Subproperties.new(self)
  @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 Attribute Details

#relations ⇒ Object (readonly)

Access to the relations object. (Used by TypeParser.)



36
37
38
 
# File 'lib/jsduck/format/doc.rb', line 36

def relations
  @relations
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.



49
50
51
52
 
# File 'lib/jsduck/format/doc.rb', line 49

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

#doc_context ⇒ Object

Returns the current documentation context



65
66
67
 
# File 'lib/jsduck/format/doc.rb', line 65

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.



56
57
58
59
60
61
62
 
# File 'lib/jsduck/format/doc.rb', line 56

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.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/jsduck/format/doc.rb', line 71

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>((<code>)?$)/, "\\1\n<pre>\\2")

  # 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

#format_subproperty(item) ⇒ Object

Recursively formats a subproperty. See Format::Subproperties#format for details.



157
158
159
 
# File 'lib/jsduck/format/doc.rb', line 157

def format_subproperty(item)
  @subproperties.format(item)
end

#format_type(type) ⇒ Object

Parses and formats type definition. Returns HTML-rendering of the type. See Format::Subproperties#format_type for details.



164
165
166
 
# File 'lib/jsduck/format/doc.rb', line 164

def format_type(type)
  @subproperties.format_type(type)
end

#images ⇒ Object 



42
43
44
 
# File 'lib/jsduck/format/doc.rb', line 42

def images
  @inline_img.images
end

#images=(images) ⇒ Object

Accessors to the images attribute of Inline::Img



39
40
41
 
# File 'lib/jsduck/format/doc.rb', line 39

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.



144
145
146
 
# File 'lib/jsduck/format/doc.rb', line 144

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.



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
141
 
# File 'lib/jsduck/format/doc.rb', line 100

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 = Format::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

#skip_type_parsing=(skip) ⇒ Object

Turns type parsing on or off.

Used to skipping parsing of CSS var and mixin types.



151
152
153
 
# File 'lib/jsduck/format/doc.rb', line 151

def skip_type_parsing=(skip)
  @subproperties.skip_type_parsing = skip
end