class Jazzy::SourceDeclaration

rubocop:disable Metrics/ClassLength

Attributes

abstract[RW]
access_control_level[RW]
async[RW]
children[R]

counterpart of parent_in_docs

column[RW]
declaration[RW]
default_impl_abstract[RW]
deprecated[RW]
deprecation_message[RW]
discussion[RW]
doc_module_name[RW]

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.

end_line[RW]
file[RW]
from_protocol_extension[RW]
generic_requirements[RW]
inherited_types[RW]
line[RW]
mark[RW]
module_name[RW]
name[RW]
nav_order[RW]
objc_name[RW]
other_language_declaration[RW]
parameters[RW]
parent_in_code[RW]

Element containing this declaration in the code

parent_in_docs[RW]

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

return[RW]
start_line[RW]
type[RW]

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

type_usr[RW]
typename[RW]

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

unavailable[RW]
unavailable_message[RW]
url[RW]
url_name[RW]
usr[RW]

Public Instance Methods

abstract_glob() click to toggle source
# 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() click to toggle source
# File lib/jazzy/source_declaration.rb, line 263
def alternative_abstract
  if file = alternative_abstract_file
    Pathname(file).read
  end
end
alternative_abstract_file() click to toggle source
# 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) click to toggle source

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

# 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
children=(new_children) click to toggle source
# File lib/jazzy/source_declaration.rb, line 46
def children=(new_children)
  # Freeze to ensure that parent_in_docs stays in sync
  @children = new_children.freeze
  @children.each { |c| c.parent_in_docs = self }
end
constrained_extension?() click to toggle source
# File lib/jazzy/source_declaration.rb, line 182
def constrained_extension?
  type.swift_extension? &&
    generic_requirements
end
declaration_note() click to toggle source

Info text for contents page by collapsed item name

# 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() click to toggle source
# 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() click to toggle source

The language in the templates for display

# 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() click to toggle source
# 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() click to toggle source

Base filename (no extension) for the item

# 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() click to toggle source

List of doc_parent decls, .last is self

# File lib/jazzy/source_declaration.rb, line 89
def docs_path
  (parent_in_docs&.docs_path || []) + [self]
end
extension_of_external_type?() click to toggle source
# File lib/jazzy/source_declaration.rb, line 221
def extension_of_external_type?
  !module_name.nil? &&
    !Config.instance.module_name?(module_name)
end
filepath() click to toggle source
# File lib/jazzy/source_declaration.rb, line 168
def filepath
  CGI.unescape(url)
end
fully_qualified_module_name() click to toggle source

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

# 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() click to toggle source
# 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() click to toggle source

‘OuterType.NestedType.method(arg:)’

# File lib/jazzy/source_declaration.rb, line 66
def fully_qualified_name
  namespace_path.map(&:name).join('.')
end
fully_qualified_name_regexp() click to toggle source

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

# 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() click to toggle source
# File lib/jazzy/source_declaration.rb, line 25
def highlight_language
  swift? ? Highlighter::SWIFT : Highlighter::OBJC
end
index_names() click to toggle source

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

# File lib/jazzy/doc_index.rb, line 181
def index_names
  [name, name.sub(/\(.*\)/, '(...)')].uniq
end
inherited_types?() click to toggle source
# File lib/jazzy/source_declaration.rb, line 195
def inherited_types?
  inherited_types &&
    !inherited_types.empty?
end
mark_for_children() click to toggle source
# 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?() click to toggle source

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

# File lib/jazzy/source_declaration.rb, line 217
def mark_undocumented?
  !swift? || (usr && !extension_of_external_type?)
end
namespace_ancestors() click to toggle source
# 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() click to toggle source

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

# File lib/jazzy/source_declaration.rb, line 53
def namespace_path
  namespace_ancestors + [self]
end
need_doc_module_note?() click to toggle source

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

# 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() click to toggle source

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.

# File lib/jazzy/source_declaration.rb, line 96
def objc_category_name
  name.split(/[()]/) if type.objc_category?
end
omit_content_from_parent?() click to toggle source

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

# 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) click to toggle source

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

# 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?() click to toggle source
# File lib/jazzy/source_declaration.rb, line 259
def readme?
  false
end
render_as_page?() click to toggle source

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

# File lib/jazzy/source_declaration.rb, line 15
def render_as_page?
  children.any? ||
    (Config.instance.separate_global_declarations &&
     type.global?)
end
swift?() click to toggle source
# File lib/jazzy/source_declaration.rb, line 21
def swift?
  type.swift_type?
end
swift_extension_objc_name() click to toggle source
# 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?() click to toggle source
# 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?() click to toggle source

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

# 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?() click to toggle source
# File lib/jazzy/source_declaration.rb, line 164
def usage_discouraged?
  unavailable || deprecated
end