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 = OpenStruct.new) ⇒ Doc

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



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

def initialize(relations={}, opts=OpenStruct.new)
  @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.)



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

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.



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

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

#doc_context ⇒ Object

Returns the current documentation context



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

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.



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

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.



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

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.



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

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.



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

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

#images ⇒ Object 



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

def images
  @inline_img.images
end

#images=(images) ⇒ Object

Accessors to the images attribute of Inline::Img



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

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.



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

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.

Replaces path/to/image.jpg Alt text with HTML from –img.

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.



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

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 SCSS var and mixin types.



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

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