jazzy 0.13.2 → 0.13.7

data/lib/jazzy/symbol_graph/relationship.rb

@@ -0,0 +1,39 @@
+module Jazzy
+  module SymbolGraph
+    # A Relationship is a tidied-up SymbolGraph JSON object
+    class Relationship
+      attr_accessor :kind
+      attr_accessor :source_usr
+      attr_accessor :target_usr
+      attr_accessor :target_fallback # can be nil
+      attr_accessor :constraints # array, can be empty
+
+      KINDS = %w[memberOf conformsTo defaultImplementationOf
+                 overrides inheritsFrom requirementOf
+                 optionalRequirementOf].freeze
+
+      def protocol_requirement?
+        %i[requirementOf optionalRequirementOf].include? kind
+      end
+
+      def default_implementation?
+        kind == :defaultImplementationOf
+      end
+
+      def initialize(hash)
+        kind = hash[:kind]
+        unless KINDS.include?(kind)
+          raise "Unknown relationship kind '#{kind}'"
+        end
+        self.kind = kind.to_sym
+        self.source_usr = hash[:source]
+        self.target_usr = hash[:target]
+        if fallback = hash[:targetFallback]
+          # Strip the leading module name
+          self.target_fallback = fallback.sub(/^.*?\./, '')
+        end
+        self.constraints = Constraint.new_list(hash[:swiftConstraints] || [])
+      end
+    end
+  end
+end

data/lib/jazzy/symbol_graph/sym_node.rb

@@ -0,0 +1,158 @@
+module Jazzy
+  module SymbolGraph
+    # The rebuilt syntax tree is made of nodes that either match
+    # symbols or that we fabricate for extensions.  This is the common
+    # treeishness.
+    class BaseNode
+      attr_accessor :children # array, can be empty
+      attr_accessor :parent # can be nil
+
+      def initialize
+        self.children = []
+      end
+
+      def add_child(child)
+        child.parent = self
+        children.append(child)
+      end
+
+      def children_to_sourcekit
+        children.sort.map(&:to_sourcekit)
+      end
+    end
+
+    # A SymNode is a node of the reconstructed syntax tree holding a symbol.
+    # It can turn itself into SourceKit and helps decode extensions.
+    class SymNode < BaseNode
+      attr_accessor :symbol
+      attr_writer :override
+      attr_writer :protocol_requirement
+      attr_writer :unlisted
+      attr_accessor :superclass_name
+
+      def override?
+        @override
+      end
+
+      def protocol_requirement?
+        @protocol_requirement
+      end
+
+      def top_level_decl?
+        !@unlisted && parent.nil?
+      end
+
+      def initialize(symbol)
+        self.symbol = symbol
+        super()
+      end
+
+      def qualified_name
+        symbol.path_components.join('.')
+      end
+
+      def parent_qualified_name
+        symbol.path_components[0...-1].join('.')
+      end
+
+      def protocol?
+        symbol.kind.end_with?('protocol')
+      end
+
+      def constraints
+        symbol.constraints
+      end
+
+      # Add another SymNode as a member if possible.
+      # It must go in an extension if either:
+      #  - it has different generic constraints to us; or
+      #  - we're a protocol and it's a default impl / ext method
+      def try_add_child(node, unique_context_constraints)
+        unless unique_context_constraints.empty? &&
+               (!protocol? || node.protocol_requirement?)
+          return false
+        end
+        add_child(node)
+        true
+      end
+
+      # The `Constraint`s on this decl that are both:
+      # 1. Unique, ie. not just inherited from its context; and
+      # 2. Constraining the *context's* gen params rather than our own.
+      def unique_context_constraints(context)
+        return symbol.constraints unless context
+
+        new_generic_type_params =
+          symbol.generic_type_params - context.symbol.generic_type_params
+
+        (symbol.constraints - context.symbol.constraints)
+          .select { |con| con.type_names.disjoint?(new_generic_type_params) }
+      end
+
+      # Messy check whether we need to fabricate an extension for a protocol
+      # conformance: don't bother if it's already in the type declaration.
+      def conformance?(protocol)
+        return false unless symbol.declaration =~ /(?<=:).*?(?=(where|$))/
+        Regexp.last_match[0] =~ /\b#{protocol}\b/
+      end
+
+      # Generate the 'where' clause for the declaration
+      def where_clause
+        parent_constraints = (parent && parent.constraints) || []
+        (constraints - parent_constraints).to_where_clause
+      end
+
+      def inherits_clause
+        return '' unless superclass_name
+        " : #{superclass_name}"
+      end
+
+      def full_declaration
+        symbol.availability
+              .append(symbol.declaration + inherits_clause + where_clause)
+              .join("\n")
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def to_sourcekit
+        declaration = full_declaration
+        xml_declaration = "<swift>#{CGI.escapeHTML(declaration)}</swift>"
+
+        hash = {
+          'key.kind' => symbol.kind,
+          'key.usr' =>  symbol.usr,
+          'key.name' => symbol.name,
+          'key.accessibility' => symbol.acl,
+          'key.parsed_decl' => declaration,
+          'key.annotated_decl' => xml_declaration,
+        }
+        if docs = symbol.doc_comments
+          hash['key.doc.comment'] = docs
+          hash['key.doc.full_as_xml'] = ''
+        end
+        if params = symbol.parameter_names
+          hash['key.doc.parameters'] =
+            params.map { |name| { 'name' => name } }
+        end
+        if location = symbol.location
+          hash['key.filepath'] = location[:filename]
+          hash['key.doc.line'] = location[:line]
+          hash['key.doc.column'] = location[:character]
+        end
+        unless children.empty?
+          hash['key.substructure'] = children_to_sourcekit
+        end
+
+        hash
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Sort order - by symbol
+      include Comparable
+
+      def <=>(other)
+        symbol <=> other.symbol
+      end
+    end
+  end
+end

data/lib/jazzy/symbol_graph/symbol.rb

@@ -0,0 +1,219 @@
+# rubocop:disable Metrics/ClassLength
+module Jazzy
+  module SymbolGraph
+    # A Symbol is a tidied-up SymbolGraph JSON object
+    class Symbol
+      attr_accessor :usr
+      attr_accessor :path_components
+      attr_accessor :declaration
+      attr_accessor :kind
+      attr_accessor :acl
+      attr_accessor :location # can be nil, keys :filename :line :character
+      attr_accessor :constraints # array, can be empty
+      attr_accessor :doc_comments # can be nil
+      attr_accessor :availability # array, can be empty
+      attr_accessor :generic_type_params # set, can be empty
+      attr_accessor :parameter_names # array, can be nil
+
+      def name
+        path_components[-1] || '??'
+      end
+
+      def initialize(hash)
+        self.usr = hash[:identifier][:precise]
+        self.path_components = hash[:pathComponents]
+        raw_decl = hash[:declarationFragments].map { |f| f[:spelling] }.join
+        init_kind(hash[:kind][:identifier])
+        init_declaration(raw_decl)
+        if func_signature = hash[:functionSignature]
+          init_func_signature(func_signature)
+        end
+        init_acl(hash[:accessLevel])
+        if location = hash[:location]
+          init_location(location)
+        end
+        init_constraints(hash, raw_decl)
+        if comments_hash = hash[:docComment]
+          init_doc_comments(comments_hash)
+        end
+        init_availability(hash[:availability] || [])
+        init_generic_type_params(hash)
+      end
+
+      # Repair problems with SymbolGraph's declprinter
+
+      def init_declaration(raw_decl)
+        # Too much 'Self.TypeName'; omitted arg labels look odd;
+        # duplicated constraints; swift 5.3 vs. master workaround
+        self.declaration =
+          raw_decl.gsub(/\bSelf\./, '')
+                  .gsub(/(?<=\(|, )_: /, '_ arg: ')
+                  .gsub(/ where.*$/, '')
+        if kind == 'source.lang.swift.decl.class'
+          declaration.sub!(/\s*:.*$/, '')
+        end
+      end
+
+      # Remember pieces of methods for later markdown parsing
+
+      def init_func_signature(func_signature)
+        self.parameter_names =
+          (func_signature[:parameters] || []).map { |h| h[:name] }
+      end
+
+      # Mapping SymbolGraph's declkinds to SourceKit
+
+      KIND_MAP = {
+        'class' => 'class',
+        'struct' => 'struct',
+        'enum' => 'enum',
+        'enum.case' => 'enumelement', # intentional
+        'protocol' => 'protocol',
+        'init' => 'function.constructor',
+        'deinit' => 'function.destructor',
+        'func.op' => 'function.operator',
+        'type.method' => 'function.method.class',
+        'static.method' => 'function.method.static',
+        'method' => 'function.method.instance',
+        'func' => 'function.free',
+        'type.property' => 'var.class',
+        'static.property' => 'var.static',
+        'property' => 'var.instance',
+        'var' => 'var.global',
+        'subscript' => 'function.subscript',
+        'type.subscript' => 'function.subscript',
+        'static.subscript' => 'function.subscript',
+        'typealias' => 'typealias',
+        'associatedtype' => 'associatedtype',
+      }.freeze
+
+      # We treat 'static var' differently to 'class var'
+      def adjust_kind_for_declaration(kind)
+        return kind unless declaration =~ /\bstatic\b/
+        kind.gsub(/type/, 'static')
+      end
+
+      def init_kind(kind)
+        adjusted = adjust_kind_for_declaration(kind)
+        sourcekit_kind = KIND_MAP[adjusted.sub('swift.', '')]
+        raise "Unknown symbol kind '#{kind}'" unless sourcekit_kind
+        self.kind = 'source.lang.swift.decl.' + sourcekit_kind
+      end
+
+      # Mapping SymbolGraph's ACL to SourceKit
+
+      def init_acl(acl)
+        self.acl = 'source.lang.swift.accessibility.' + acl
+      end
+
+      # Symbol location - only available for public+ decls
+
+      def init_location(loc_hash)
+        self.location = {}
+        location[:filename] = loc_hash[:uri].sub(%r{^file://}, '')
+        location[:line] = loc_hash[:position][:line]
+        location[:character] = loc_hash[:position][:character]
+      end
+
+      # Generic constraints: in one or both of two places.
+      # There can be duplicates; these are removed by `Constraint`.
+      def init_constraints(hash, raw_decl)
+        raw_constraints = %i[swiftGenerics swiftExtension].flat_map do |key|
+          next [] unless container = hash[key]
+          container[:constraints] || []
+        end
+
+        constraints =
+          Constraint.new_list_for_symbol(raw_constraints, path_components)
+        if raw_decl =~ / where (.*)$/
+          constraints +=
+            Constraint.new_list_from_declaration(Regexp.last_match[1])
+        end
+
+        self.constraints = constraints.sort.uniq
+      end
+
+      # Generic type params
+      def init_generic_type_params(hash)
+        self.generic_type_params = Set.new(
+          if (generics = hash[:swiftGenerics]) &&
+             (parameters = generics[:parameters])
+            parameters.map { |p| p[:name] }
+          else
+            []
+          end,
+        )
+      end
+
+      def init_doc_comments(comments_hash)
+        self.doc_comments =
+          comments_hash[:lines].map { |l| l[:text] }
+                               .join("\n")
+      end
+
+      # Availability
+      # Re-encode this as Swift.  Should really teach Jazzy about these,
+      # could maybe then do something smarter here.
+      def init_availability(avail_hash_list)
+        self.availability = avail_hash_list.map do |avail|
+          str = '@available('
+          if avail[:isUnconditionallyDeprecated]
+            str += '*, deprecated'
+          elsif domain = avail[:domain]
+            str += domain
+            %i[introduced deprecated obsoleted].each do |event|
+              if version = avail[event]
+                str += ", #{event}: #{decode_version(version)}"
+              end
+            end
+          else
+            warn "Found confusing availability: #{avail}"
+            next nil
+          end
+
+          str += ', message: "' + avail[:message] + '"' if avail[:message]
+          str += ', renamed: "' + avail[:renamed] + '"' if avail[:renamed]
+
+          str + ')'
+        end.compact
+      end
+
+      def decode_version(hash)
+        str = hash[:major].to_s
+        str += ".#{hash[:minor]}" if hash[:minor]
+        str += ".#{hash[:patch]}" if hash[:patch]
+        str
+      end
+
+      # Sort order
+      include Comparable
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+      def <=>(other)
+        # Things with location: order by file/line/column
+        # (pls tell what wheel i am reinventing :/)
+        if location && other_loc = other.location
+          if location[:filename] == other_loc[:filename]
+            if location[:line] == other_loc[:line]
+              return location[:character] <=> other_loc[:character]
+            end
+            return location[:line] <=> other_loc[:line]
+          end
+          return location[:filename] <=> other_loc[:filename]
+        end
+
+        # Things with a location before things without a location
+        return +1 if location.nil? && other.location
+        return -1 if location && other.location.nil?
+
+        # Things without a location: by name and then USR
+        return usr <=> other.usr if name == other.name
+        name <=> other.name
+      end
+      # rubocop:enable Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss

@@ -18,12 +18,13 @@ $content_wrapper_width: 980px;
 $content_top_offset: 70px;
 $content_body_margin: 16px;
 $content_body_left_offset: $sidebar_width + $content_body_margin;
-$header_height: 26px;
+$header_height: 32px;
 $breadcrumb_padding_top: 17px;
 
 $code_font: 0.95em Menlo, monospace;
 
-$gray_border: 1px solid #e2e2e2;
+$gray_border_color: #e2e2e2;
+$gray_border: 1px solid $gray_border_color;
 $declaration_language_border: 5px solid #cde9f4;
 
 $aside_color: #aaa;
@@ -104,12 +105,18 @@ p code, li code {
   padding: 2px 4px;
   border-radius: 4px;
 }
+pre > code {
+  padding: 0;
+}
 
 // Links
 
 a {
   color: $link_color;
   text-decoration: none;
+  code {
+    color: inherit;
+  }
 }
 
 // Lists
@@ -135,6 +142,25 @@ blockquote {
   border-left: 4px solid #ccc;
 }
 
+// HRs
+
+hr {
+  height: 1px;
+  border: none;
+  background-color: $gray_border_color;
+}
+
+// Footnotes
+
+.footnote-ref {
+  display: inline-block;
+  scroll-margin-top: $content-top-offset;
+}
+
+.footnote-def {
+  scroll-margin-top: $content-top-offset;
+}
+
 // General Content Wrapper
 
 .content-wrapper {
@@ -152,7 +178,7 @@ header {
   background-color: $bg_color;
   position: fixed;
   width: 100%;
-  z-index: 2;
+  z-index: 3;
   img {
     padding-right: 6px;
     vertical-align: -4px;
@@ -309,6 +335,7 @@ header {
 }
 
 .task-group-section {
+  margin-top: 10px;
   padding-left: 6px;
   border-top: $gray_border;
 }
@@ -529,3 +556,69 @@ html.dash {
     position: static;
   }
 }
+
+// ===========================================================================
+//
+//  Search
+//
+// ===========================================================================
+form[role=search] {
+  float: right;
+
+  input {
+    font: Helvetica, freesans, Arial, sans-serif;
+    margin-top: 6px;
+    font-size: 13px;
+    line-height: 20px;
+    padding: 0px 10px;
+    border: none;
+    border-radius: 1em;
+    .loading & {
+      background: white url(../img/spinner.gif) center right 4px no-repeat;
+    }
+  }
+
+  // Typeahead elements
+
+  .tt-menu {
+    margin: 0;
+    min-width: 300px;
+    background: $white_color;
+    color: #333;
+    border: $gray_border;
+    z-index: 4;
+  }
+
+  .tt-highlight {
+    font-weight: bold;
+  }
+
+  .tt-suggestion {
+    font: Helvetica, freesans, Arial, sans-serif;
+    font-size: 14px;
+    padding: 0 8px;
+    span {
+      display: table-cell;
+      white-space: nowrap;
+    }
+    .doc-parent-name {
+      width: 100%;
+      text-align: right;
+      font-weight: normal;
+      font-size: 0.9em;
+      padding-left: 16px;
+    }
+  }
+
+  .tt-suggestion:hover,
+  .tt-suggestion.tt-cursor {
+    cursor: pointer;
+    background-color: #4183c4;
+    color: #fff;
+  }
+
+  .tt-suggestion:hover .doc-parent-name,
+  .tt-suggestion.tt-cursor .doc-parent-name {
+    color: #fff;
+  }
+}