class Jazzy::SourceDeclaration
rubocop:disable Metrics/ClassLength
Attributes
counterpart of parent_in_docs
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.
Element containing this declaration in the code
Logical parent in the documentation. May differ from parent_in_code
because of top-level categories and merged extensions.
kind of declaration (e.g. class, variable, function)
static type of declared element (e.g. String.Type -> ())
Public Instance Methods
# 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
# File lib/jazzy/source_declaration.rb, line 263 def alternative_abstract if file = alternative_abstract_file Pathname(file).read end end
# 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
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
# 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
# File lib/jazzy/source_declaration.rb, line 182 def constrained_extension? type.swift_extension? && generic_requirements end
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
# File lib/jazzy/source_declaration.rb, line 117 def display_declaration return declaration if swift? Config.instance.hide_objc? ? other_language_declaration : declaration end
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
# 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
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
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
# File lib/jazzy/source_declaration.rb, line 221 def extension_of_external_type? !module_name.nil? && !Config.instance.module_name?(module_name) end
# File lib/jazzy/source_declaration.rb, line 168 def filepath CGI.unescape(url) end
‘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
# 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
‘OuterType.NestedType.method(arg:)’
# File lib/jazzy/source_declaration.rb, line 66 def fully_qualified_name namespace_path.map(&:name).join('.') end
: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
# File lib/jazzy/source_declaration.rb, line 25 def highlight_language swift? ? Highlighter::SWIFT : Highlighter::OBJC end
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
# File lib/jazzy/source_declaration.rb, line 195 def inherited_types? inherited_types && !inherited_types.empty? end
# 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
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
# File lib/jazzy/source_declaration.rb, line 57 def namespace_ancestors if parent_in_code parent_in_code.namespace_path else [] end end
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
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
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
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
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
# File lib/jazzy/source_declaration.rb, line 259 def readme? false end
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
# File lib/jazzy/source_declaration.rb, line 21 def swift? type.swift_type? end
# File lib/jazzy/source_declaration.rb, line 104 def swift_extension_objc_name return unless type.swift_extension? && usr usr.split('(cs)').last end
# File lib/jazzy/source_declaration.rb, line 100 def swift_objc_extension? type.swift_extension? && usr && usr.start_with?('c:objc') end
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
# File lib/jazzy/source_declaration.rb, line 164 def usage_discouraged? unavailable || deprecated end