Class: Jazzy::SourceDeclaration

Inherits:
Object
  • Object
show all
Defined in:
lib/jazzy/source_declaration.rb,
lib/jazzy/doc_index.rb,
lib/jazzy/source_declaration/type.rb,
lib/jazzy/source_declaration/access_control_level.rb

Overview

rubocop:disable Metrics/ClassLength

Direct Known Subclasses

SourceDocument

Defined Under Namespace

Classes: AccessControlLevel, Type

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#abstract ⇒ Object

Returns the value of attribute abstract.



138
139
140
 
# File 'lib/jazzy/source_declaration.rb', line 138

def abstract
  @abstract
end

#access_control_level ⇒ Object

Returns the value of attribute access_control_level.



146
147
148
 
# File 'lib/jazzy/source_declaration.rb', line 146

def access_control_level
  @access_control_level
end

#async ⇒ Object

Returns the value of attribute async.



157
158
159
 
# File 'lib/jazzy/source_declaration.rb', line 157

def async
  @async
end

#children ⇒ Object

counterpart of parent_in_docs



44
45
46
 
# File 'lib/jazzy/source_declaration.rb', line 44

def children
  @children
end

#column ⇒ Object

Returns the value of attribute column.



130
131
132
 
# File 'lib/jazzy/source_declaration.rb', line 130

def column
  @column
end

#declaration ⇒ Object

Returns the value of attribute declaration.



136
137
138
 
# File 'lib/jazzy/source_declaration.rb', line 136

def declaration
  @declaration
end

#default_impl_abstract ⇒ Object

Returns the value of attribute default_impl_abstract.



139
140
141
 
# File 'lib/jazzy/source_declaration.rb', line 139

def default_impl_abstract
  @default_impl_abstract
end

#deprecated ⇒ Object

Returns the value of attribute deprecated.



151
152
153
 
# File 'lib/jazzy/source_declaration.rb', line 151

def deprecated
  @deprecated
end

#deprecation_message ⇒ Object

Returns the value of attribute deprecation_message.



152
153
154
 
# File 'lib/jazzy/source_declaration.rb', line 152

def deprecation_message
  @deprecation_message
end

#discussion ⇒ Object

Returns the value of attribute discussion.



141
142
143
 
# File 'lib/jazzy/source_declaration.rb', line 141

def discussion
  @discussion
end

#doc_module_name ⇒ Object

The name of the module being documented that contains this declaration. Only different from module_name when this is an extension of a type from another module. Nil for guides.



162
163
164
 
# File 'lib/jazzy/source_declaration.rb', line 162

def doc_module_name
  @doc_module_name
end

#end_line ⇒ Object

Returns the value of attribute end_line.



148
149
150
 
# File 'lib/jazzy/source_declaration.rb', line 148

def end_line
  @end_line
end

#file ⇒ Object

Returns the value of attribute file.



128
129
130
 
# File 'lib/jazzy/source_declaration.rb', line 128

def file
  @file
end

#from_protocol_extension ⇒ Object

Returns the value of attribute from_protocol_extension.



140
141
142
 
# File 'lib/jazzy/source_declaration.rb', line 140

def from_protocol_extension
  @from_protocol_extension
end

#generic_requirements ⇒ Object

Returns the value of attribute generic_requirements.



155
156
157
 
# File 'lib/jazzy/source_declaration.rb', line 155

def generic_requirements
  @generic_requirements
end

#inherited_types ⇒ Object

Returns the value of attribute inherited_types.



156
157
158
 
# File 'lib/jazzy/source_declaration.rb', line 156

def inherited_types
  @inherited_types
end

#line ⇒ Object

Returns the value of attribute line.



129
130
131
 
# File 'lib/jazzy/source_declaration.rb', line 129

def line
  @line
end

#mark ⇒ Object

Returns the value of attribute mark.



145
146
147
 
# File 'lib/jazzy/source_declaration.rb', line 145

def mark
  @mark
end

#module_name ⇒ Object

Returns the value of attribute module_name.



133
134
135
 
# File 'lib/jazzy/source_declaration.rb', line 133

def module_name
  @module_name
end

#name ⇒ Object

Returns the value of attribute name.



134
135
136
 
# File 'lib/jazzy/source_declaration.rb', line 134

def name
  @name
end

#nav_order ⇒ Object

Returns the value of attribute nav_order.



149
150
151
 
# File 'lib/jazzy/source_declaration.rb', line 149

def nav_order
  @nav_order
end

#objc_name ⇒ Object

Returns the value of attribute objc_name.



135
136
137
 
# File 'lib/jazzy/source_declaration.rb', line 135

def objc_name
  @objc_name
end

#other_language_declaration ⇒ Object

Returns the value of attribute other_language_declaration.



137
138
139
 
# File 'lib/jazzy/source_declaration.rb', line 137

def other_language_declaration
  @other_language_declaration
end

#parameters ⇒ Object

Returns the value of attribute parameters.



143
144
145
 
# File 'lib/jazzy/source_declaration.rb', line 143

def parameters
  @parameters
end

#parent_in_code ⇒ Object

Element containing this declaration in the code



37
38
39
 
# File 'lib/jazzy/source_declaration.rb', line 37

def parent_in_code
  @parent_in_code
end

#parent_in_docs ⇒ Object

Logical parent in the documentation. May differ from parent_in_code because of top-level categories and merged extensions.



41
42
43
 
# File 'lib/jazzy/source_declaration.rb', line 41

def parent_in_docs
  @parent_in_docs
end

#return ⇒ Object

Returns the value of attribute return.



142
143
144
 
# File 'lib/jazzy/source_declaration.rb', line 142

def return
  @return
end

#start_line ⇒ Object

Returns the value of attribute start_line.



147
148
149
 
# File 'lib/jazzy/source_declaration.rb', line 147

def start_line
  @start_line
end

#type ⇒ Object

kind of declaration (e.g. class, variable, function)



10
11
12
 
# File 'lib/jazzy/source_declaration.rb', line 10

def type
  @type
end

#type_usr ⇒ Object

Returns the value of attribute type_usr.



132
133
134
 
# File 'lib/jazzy/source_declaration.rb', line 132

def type_usr
  @type_usr
end

#typename ⇒ Object

static type of declared element (e.g. String.Type -> ())



12
13
14
 
# File 'lib/jazzy/source_declaration.rb', line 12

def typename
  @typename
end

#unavailable ⇒ Object

Returns the value of attribute unavailable.



153
154
155
 
# File 'lib/jazzy/source_declaration.rb', line 153

def unavailable
  @unavailable
end

#unavailable_message ⇒ Object

Returns the value of attribute unavailable_message.



154
155
156
 
# File 'lib/jazzy/source_declaration.rb', line 154

def unavailable_message
  @unavailable_message
end

#url ⇒ Object

Returns the value of attribute url.



144
145
146
 
# File 'lib/jazzy/source_declaration.rb', line 144

def url
  @url
end

#url_name ⇒ Object

Returns the value of attribute url_name.



150
151
152
 
# File 'lib/jazzy/source_declaration.rb', line 150

def url_name
  @url_name
end

#usr ⇒ Object

Returns the value of attribute usr.



131
132
133
 
# File 'lib/jazzy/source_declaration.rb', line 131

def usr
  @usr
end

Instance Method Details

#abstract_glob ⇒ Object 



276
277
278
279
280
281
282
 
# File 'lib/jazzy/source_declaration.rb', line 276

def abstract_glob
  return [] unless
    Config.instance.abstract_glob_configured &&
    Config.instance.abstract_glob

  Config.instance.abstract_glob.select { |e| File.file? e }
end

#alternative_abstract ⇒ Object 



263
264
265
266
267
 
# File 'lib/jazzy/source_declaration.rb', line 263

def alternative_abstract
  if file = alternative_abstract_file
    Pathname(file).read
  end
end

#alternative_abstract_file ⇒ Object 



269
270
271
272
273
274
 
# File 'lib/jazzy/source_declaration.rb', line 269

def alternative_abstract_file
  abstract_glob.select do |f|
    # allow Structs.md or Structures.md
    [name, url_name].include?(File.basename(f).split('.').first)
  end.first
end

#ambiguous_module_name?(group_name) ⇒ Boolean

Is it unclear from context what module the (top-level) decl is from?

Returns:

  • (Boolean) 


227
228
229
230
231
232
 
# File 'lib/jazzy/source_declaration.rb', line 227

def ambiguous_module_name?(group_name)
  extension_of_external_type? ||
    (Config.instance.multiple_modules? &&
      !module_name.nil? &&
      group_name != module_name)
end

#constrained_extension? ⇒ Boolean

Returns:

  • (Boolean) 


182
183
184
185
 
# File 'lib/jazzy/source_declaration.rb', line 182

def constrained_extension?
  type.swift_extension? &&
    generic_requirements
end

#declaration_note ⇒ Object

Info text for contents page by collapsed item name



249
250
251
252
253
254
255
256
257
 
# File 'lib/jazzy/source_declaration.rb', line 249

def declaration_note
  notes = [
    default_impl_abstract ? 'default implementation' : nil,
    from_protocol_extension ? 'extension method' : nil,
    async ? 'asynchronous' : nil,
    need_doc_module_note? ? "from #{doc_module_name}" : nil,
  ].compact
  notes.join(', ').upcase_first unless notes.empty?
end

#display_declaration ⇒ Object 



117
118
119
120
121
 
# File 'lib/jazzy/source_declaration.rb', line 117

def display_declaration
  return declaration if swift?

  Config.instance.hide_objc? ? other_language_declaration : declaration
end

#display_language ⇒ Object

The language in the templates for display



111
112
113
114
115
 
# File 'lib/jazzy/source_declaration.rb', line 111

def display_language
  return 'Swift' if swift?

  Config.instance.hide_objc? ? 'Swift' : 'Objective-C'
end

#display_other_language_declaration ⇒ Object 



123
124
125
126
 
# File 'lib/jazzy/source_declaration.rb', line 123

def display_other_language_declaration
  other_language_declaration unless
    Config.instance.hide_objc? || Config.instance.hide_swift?
end

#docs_filename ⇒ Object

Base filename (no extension) for the item



173
174
175
176
177
178
179
180
 
# File 'lib/jazzy/source_declaration.rb', line 173

def docs_filename
  result = url_name || name
  # Workaround functions sharing names with
  # different argument types (f(a:Int) vs. f(a:String))
  return result unless type.swift_global_function?

  result + "_#{type_usr}"
end

#docs_path ⇒ Object

List of doc_parent decls, .last is self



89
90
91
 
# File 'lib/jazzy/source_declaration.rb', line 89

def docs_path
  (parent_in_docs&.docs_path || []) + [self]
end

#extension_of_external_type? ⇒ Boolean

Returns:

  • (Boolean) 


221
222
223
224
 
# File 'lib/jazzy/source_declaration.rb', line 221

def extension_of_external_type?
  !module_name.nil? &&
    !Config.instance.module_name?(module_name)
end

#filepath ⇒ Object 



168
169
170
 
# File 'lib/jazzy/source_declaration.rb', line 168

def filepath
  CGI.unescape(url)
end

#fully_qualified_module_name ⇒ Object

‘MyModule.OuterType.NestedType.method(arg:)’



84
85
86
 
# File 'lib/jazzy/source_declaration.rb', line 84

def fully_qualified_module_name
  fully_qualified_module_name_parts.join('.')
end

#fully_qualified_module_name_parts ⇒ Object 



78
79
80
81
 
# File 'lib/jazzy/source_declaration.rb', line 78

def fully_qualified_module_name_parts
  path = namespace_path
  path.map(&:name).prepend(path.first.module_name).compact
end

#fully_qualified_name ⇒ Object

‘OuterType.NestedType.method(arg:)’



66
67
68
 
# File 'lib/jazzy/source_declaration.rb', line 66

def fully_qualified_name
  namespace_path.map(&:name).join('.')
end

#fully_qualified_name_regexp ⇒ Object

:name doesn’t include any generic type params. This regexp matches any generic type params in parent names.



72
73
74
75
76
 
# File 'lib/jazzy/source_declaration.rb', line 72

def fully_qualified_name_regexp
  Regexp.new(namespace_path.map(&:name)
                           .map { |n| Regexp.escape(n) }
                           .join('(?:<.*?>)?\.'))
end

#highlight_language ⇒ Object 



25
26
27
 
# File 'lib/jazzy/source_declaration.rb', line 25

def highlight_language
  swift? ? Highlighter::SWIFT : Highlighter::OBJC
end

#index_names ⇒ Object

Names for a symbol. Permits function parameters to be omitted.



181
182
183
 
# File 'lib/jazzy/doc_index.rb', line 181

def index_names
  [name, name.sub(/\(.*\)/, '(...)')].uniq
end

#inherited_types? ⇒ Boolean

Returns:

  • (Boolean) 


195
196
197
198
 
# File 'lib/jazzy/source_declaration.rb', line 195

def inherited_types?
  inherited_types &&
    !inherited_types.empty?
end

#mark_for_children ⇒ Object 



187
188
189
190
191
192
193
 
# File 'lib/jazzy/source_declaration.rb', line 187

def mark_for_children
  if constrained_extension?
    SourceMark.new_generic_requirements(generic_requirements)
  else
    SourceMark.new
  end
end

#mark_undocumented? ⇒ Boolean

Don’t ask the user to write documentation for types being extended from other modules. Compile errors leave no docs and a ‘nil` USR.

Returns:

  • (Boolean) 


217
218
219
 
# File 'lib/jazzy/source_declaration.rb', line 217

def mark_undocumented?
  !swift? || (usr && !extension_of_external_type?)
end

#namespace_ancestors ⇒ Object 



57
58
59
60
61
62
63
 
# File 'lib/jazzy/source_declaration.rb', line 57

def namespace_ancestors
  if parent_in_code
    parent_in_code.namespace_path
  else
    []
  end
end

#namespace_path ⇒ Object

Chain of parent_in_code from top level to self. (Includes self.)



53
54
55
 
# File 'lib/jazzy/source_declaration.rb', line 53

def namespace_path
  namespace_ancestors + [self]
end

#need_doc_module_note? ⇒ Boolean

Does the user need help understanding how to get this declaration?

Returns:

  • (Boolean) 


235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/jazzy/source_declaration.rb', line 235

def need_doc_module_note?
  return false unless Config.instance.multiple_modules?
  return false if docs_path.first.name == doc_module_name

  if parent_in_code.nil?
    # Top-level decls with no page of their own
    !render_as_page?
  else
    # Members added by extension
    parent_in_code.module_name != doc_module_name
  end
end

#objc_category_name ⇒ Object

If this declaration is an objc category, returns an array with the name of the extended objc class and the category name itself, i.e. [“NSString”, “MyMethods”], nil otherwise.



96
97
98
 
# File 'lib/jazzy/source_declaration.rb', line 96

def objc_category_name
  name.split(/[()]/) if type.objc_category?
end

#omit_content_from_parent? ⇒ Boolean

When referencing this item from its parent category, include the content or just link to it directly?

Returns:

  • (Boolean) 


31
32
33
34
 
# File 'lib/jazzy/source_declaration.rb', line 31

def omit_content_from_parent?
  Config.instance.separate_global_declarations &&
    render_as_page?
end

#other_inherited_types?(unwanted) ⇒ Boolean

Is there at least one inherited type that is not in the given list?

Returns:

  • (Boolean) 


201
202
203
204
205
 
# File 'lib/jazzy/source_declaration.rb', line 201

def other_inherited_types?(unwanted)
  return false unless inherited_types?

  inherited_types.any? { |t| !unwanted.include?(t) }
end

#readme? ⇒ Boolean

Returns:

  • (Boolean) 


259
260
261
 
# File 'lib/jazzy/source_declaration.rb', line 259

def readme?
  false
end

#render_as_page? ⇒ Boolean

Give the item its own page or just inline into parent?

Returns:

  • (Boolean) 


15
16
17
18
19
 
# File 'lib/jazzy/source_declaration.rb', line 15

def render_as_page?
  children.any? ||
    (Config.instance.separate_global_declarations &&
     type.global?)
end

#swift? ⇒ Boolean

Returns:

  • (Boolean) 


21
22
23
 
# File 'lib/jazzy/source_declaration.rb', line 21

def swift?
  type.swift_type?
end

#swift_extension_objc_name ⇒ Object 



104
105
106
107
108
 
# File 'lib/jazzy/source_declaration.rb', line 104

def swift_extension_objc_name
  return unless type.swift_extension? && usr

  usr.split('(cs)').last
end

#swift_objc_extension? ⇒ Boolean

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/jazzy/source_declaration.rb', line 100

def swift_objc_extension?
  type.swift_extension? && usr && usr.start_with?('c:objc')
end

#type_from_doc_module? ⇒ Boolean

Pre-Swift 5.6: SourceKit only sets module_name for imported modules Swift 5.6+: module_name is always set

Returns:

  • (Boolean) 


209
210
211
212
213
 
# File 'lib/jazzy/source_declaration.rb', line 209

def type_from_doc_module?
  !type.extension? ||
    (swift? && usr &&
      (module_name.nil? || module_name == doc_module_name))
end

#usage_discouraged? ⇒ Boolean

Returns:

  • (Boolean) 


164
165
166
 
# File 'lib/jazzy/source_declaration.rb', line 164

def usage_discouraged?
  unavailable || deprecated
end