Class: JsDuck::Tag::Tag

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

Overview

Base class for all builtin tags.

Constant Summary collapse

POS_ASIDE = 
1
POS_PRIVATE = 
2
POS_DOC = 
3
POS_LOCALDOC = 
4
POS_DEFAULT = 
5
POS_SINCE = 
6
POS_DEPRECATED = 
7
POS_ENUM = 
8
POS_TEMPLATE = 
9
POS_PREVENTABLE = 
10
POS_PARAM = 
11
POS_SUBPROPERTIES = 
12
POS_RETURN = 
13
POS_THROWS = 
14
POS_FIRES = 
15
POS_OVERRIDES = 
16
PRIORITY_SINGLETON = 
2
PRIORITY_COMPONENT = 
1
PRIORITY_CLASS = 
0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#class_icon ⇒ Object (readonly)

Defines custom class icon files.

It must be a hash with the following keys:

  • :large - the large icon used in class header

  • :small - small icon used in class tree and search

  • :redirect - redirect icon for alternateClassNames in search.

  • :priority - a number to determine which icon gets used when

    a class has several tags that set a custom icon.  An icon
with a larger priority wins.

Used by @class tag to define the default icon. Used by @singleton and @component tags for a different icon.



149
150
151
 
# File 'lib/jsduck/tag/tag.rb', line 149

def class_icon
  @class_icon
end

#css ⇒ Object (readonly)

A string of CSS to add to the builtin CSS of the generated docs. For example, to style a signature label:

@css = ".signature .mytag { color: red }"



134
135
136
 
# File 'lib/jsduck/tag/tag.rb', line 134

def css
  @css
end

#ext_define_default ⇒ Object (readonly)

The default value to use when Ext.define is encountered, but the key in the config object itself is not found. This must be a Hash defining the key and value.



67
68
69
 
# File 'lib/jsduck/tag/tag.rb', line 67

def ext_define_default
  @ext_define_default
end

#ext_define_pattern ⇒ Object (readonly)

Defines the name of object property in Ext.define() configuration which, when encountered, will cause the #parse_ext_define method to be invoked.



62
63
64
 
# File 'lib/jsduck/tag/tag.rb', line 62

def ext_define_pattern
  @ext_define_pattern
end

#html_position ⇒ Object

The position for outputting the HTML for the tag in final documentation.

Must be defined together with #to_html method. Additionally the #format method can be defined to perform rendering of Markdown before #to_html is called.

All builtin tags have a position that’s defined by one of the constants listed below. For user-defined tags it’s recommended to define your position relative to one of the builtin tags. For example if you want your tag to output HTML right after the return value documentation, use something like:

@html_position = POS_RETURN + 0.1

Later versions of JSDuck might change the actual values of these constants, so don’t rely on the concrete values, reference the constants and add/substract fractions smaller than 1 from them.



95
96
97
 
# File 'lib/jsduck/tag/tag.rb', line 95

def html_position
  @html_position
end

#pattern ⇒ Object (readonly)

Defines the name of the @tag. The name itself must not contain the “@” sign. For example: “cfg”



7
8
9
 
# File 'lib/jsduck/tag/tag.rb', line 7

def pattern
  @pattern
end

#repeatable ⇒ Object (readonly)

Set to true to allow the tag to occour multiple times within one doc-comment. By default a tag can only appear once and when it’s detected several times a warning will be generated.



12
13
14
 
# File 'lib/jsduck/tag/tag.rb', line 12

def repeatable
  @repeatable
end

#signature ⇒ Object (readonly)

The text to display in member signature. Must be a hash defining the short and long versions of the signature text:

{:long => "something", :short => "SOM"}

Additionally the hash can contain a :tooltip which is the text to be shown when the signature bubble is hovered over in docs.



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

def signature
  @signature
end

#tagname ⇒ Object (readonly)

Defines the symbol under which the tag data is stored in final member/class hash.



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

def tagname
  @tagname
end

Class Method Details

.descendants ⇒ Object

Returns all descendants of JsDuck::Tag::Tag class.



156
157
158
159
160
161
162
 
# File 'lib/jsduck/tag/tag.rb', line 156

def self.descendants
  result = []
  ObjectSpace.each_object(::Class) do |cls|
    result << cls if cls < self
  end
  result
end

Instance Method Details

#format(context, formatter) ⇒ Object

Called before #to_html to allow rendering of Markdown content. For this an instance of DocFormatter is passed in, on which one can call the #format method to turn Markdown into HTML.



117
118
 
# File 'lib/jsduck/tag/tag.rb', line 117

def format(context, formatter)
end

#parse_doc(scanner, position) ⇒ Object

Called by DocParser when the @tag is reached to do the parsing from that point forward. Gets passed an instance of DocScanner.

Can return a hash or array of hashes representing the detected e.g.:

{:tagname => :protected, :foo => "blah"}

All hashes with the same :tagname will later be combined together and passed on to #process_doc method of this Tag class that has @tagname field set to that tagname.

The hash can also contain :doc => :multiline, in which case all the documentation following this tag will get added to the :doc field of the tag and will later be accessible in #process_doc method.

Also a hash with position information :linenr is passed in.



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

def parse_doc(scanner, position)
end

#parse_ext_define(cls, ast) ⇒ Object

Called by Ast class to parse a config in Ext.define(). various properties can be set.

Parameters:

  • cls (Hash) —

    A simple Hash representing a class on which

  • ast (AstNode) —

    Value of the config in Ext.define().



73
74
 
# File 'lib/jsduck/tag/tag.rb', line 73

def parse_ext_define(cls, ast)
end

#process_doc(hash, docs, position) ⇒ Object

Gets called with the resulting class/member hash and array of position information :linenr is passed in.

It can then add a new field to the class/member hash or transform it in any other way desired.



47
48
 
# File 'lib/jsduck/tag/tag.rb', line 47

def process_doc(hash, docs, position)
end

#to_html(context) ⇒ Object

Implement #to_html to transform tag data to HTML to be included into documentation.

It gets passed the full class/member hash. It should return an HTML string to inject into document.



126
127
 
# File 'lib/jsduck/tag/tag.rb', line 126

def to_html(context)
end