jazzy 0.14.3 → 0.14.4

data/lib/jazzy/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jazzy
-  VERSION = '0.14.3' unless defined? Jazzy::VERSION
+  VERSION = '0.14.4' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/search_builder.rb

@@ -10,7 +10,7 @@ module Jazzy
         [d.url,
          {
            name: d.name,
-           abstract: d.abstract && d.abstract.split(/\n/).map(&:strip).first,
+           abstract: d.abstract && d.abstract.split("\n").map(&:strip).first,
            parent_name: d.parent_in_code&.name,
          }.reject { |_, v| v.nil? || v.empty? }]
       end

data/lib/jazzy/source_declaration/access_control_level.rb

@@ -5,106 +5,94 @@ module Jazzy
     class AccessControlLevel
       include Comparable
 
+      # Order matters
+      LEVELS = %i[private fileprivate internal package public open].freeze
+
+      LEVELS_INDEX = LEVELS.to_h { |i| [i, LEVELS.index(i)] }.freeze
+
       attr_reader :level
 
-      ACCESSIBILITY_PRIVATE = 'source.lang.swift.accessibility.private'
-      ACCESSIBILITY_FILEPRIVATE =
-        'source.lang.swift.accessibility.fileprivate'
-      ACCESSIBILITY_INTERNAL = 'source.lang.swift.accessibility.internal'
-      ACCESSIBILITY_PUBLIC = 'source.lang.swift.accessibility.public'
-      ACCESSIBILITY_OPEN = 'source.lang.swift.accessibility.open'
-
-      def initialize(accessibility)
-        @level = case accessibility
-                 when ACCESSIBILITY_PRIVATE then :private
-                 when ACCESSIBILITY_FILEPRIVATE then :fileprivate
-                 when ACCESSIBILITY_INTERNAL then :internal
-                 when ACCESSIBILITY_PUBLIC then :public
-                 when ACCESSIBILITY_OPEN then :open
-                 else
-                   raise 'cannot initialize AccessControlLevel with ' \
-                     "'#{accessibility}'"
-                 end
+      def initialize(level)
+        @level = level
+      end
+
+      # From a SourceKit accessibility string
+      def self.from_accessibility(accessibility)
+        return nil if accessibility.nil?
+
+        if accessibility =~ /^source\.lang\.swift\.accessibility\.(.*)$/ &&
+           (matched = Regexp.last_match(1).to_sym) &&
+           !LEVELS_INDEX[matched].nil?
+          return new(matched)
+        end
+
+        raise "cannot initialize AccessControlLevel with '#{accessibility}'"
       end
 
+      # From a SourceKit declaration hash
       def self.from_doc(doc)
         return AccessControlLevel.internal if implicit_deinit?(doc)
 
-        accessibility = doc['key.accessibility']
-        if accessibility
-          acl = new(accessibility)
-          if acl
-            return acl
-          end
-        end
-        acl = from_doc_explicit_declaration(doc)
-        acl || AccessControlLevel.internal # fallback on internal ACL
+        from_documentation_attribute(doc) ||
+          from_accessibility(doc['key.accessibility']) ||
+          from_doc_explicit_declaration(doc) ||
+          AccessControlLevel.internal # fallback on internal ACL
       end
 
+      # Workaround `deinit` being always technically public
       def self.implicit_deinit?(doc)
         doc['key.name'] == 'deinit' &&
           from_doc_explicit_declaration(doc).nil?
       end
 
+      # From a Swift declaration
       def self.from_doc_explicit_declaration(doc)
-        case doc['key.parsed_declaration']
-        when /private\ / then private
-        when /fileprivate\ / then fileprivate
-        when /public\ / then public
-        when /open\ / then open
-        when /internal\ / then internal
+        declaration = doc['key.parsed_declaration']
+        LEVELS.each do |level|
+          if declaration =~ /\b#{level}\b/
+            return send(level)
+          end
         end
+        nil
       end
 
+      # From a config instruction
       def self.from_human_string(string)
-        case string.to_s.downcase
-        when 'private' then private
-        when 'fileprivate' then fileprivate
-        when 'internal' then internal
-        when 'public' then public
-        when 'open' then open
-        else raise "cannot initialize AccessControlLevel with '#{string}'"
+        normalized = string.to_s.downcase.to_sym
+        if LEVELS_INDEX[normalized].nil?
+          raise "cannot initialize AccessControlLevel with '#{string}'"
         end
-      end
-
-      def self.private
-        new(ACCESSIBILITY_PRIVATE)
-      end
 
-      def self.fileprivate
-        new(ACCESSIBILITY_FILEPRIVATE)
+        send(normalized)
       end
 
-      def self.internal
-        new(ACCESSIBILITY_INTERNAL)
+      # From a @_documentation(visibility:) attribute
+      def self.from_documentation_attribute(doc)
+        if doc['key.annotated_decl'] =~ /@_documentation\(\s*visibility\s*:\s*(\w+)/
+          from_human_string(Regexp.last_match[1])
+        end
       end
 
-      def self.public
-        new(ACCESSIBILITY_PUBLIC)
-      end
+      # Define `AccessControlLevel.public` etc.
 
-      def self.open
-        new(ACCESSIBILITY_OPEN)
+      LEVELS.each do |level|
+        define_singleton_method(level) do
+          new(level)
+        end
       end
 
-      LEVELS = {
-        private: 0,
-        fileprivate: 1,
-        internal: 2,
-        public: 3,
-        open: 4,
-      }.freeze
+      # Comparing access levels
 
       def <=>(other)
-        LEVELS[level] <=> LEVELS[other.level]
+        LEVELS_INDEX[level] <=> LEVELS_INDEX[other.level]
       end
 
       def included_levels
-        LEVELS.select { |_, v| v >= LEVELS[level] }.keys
+        LEVELS_INDEX.select { |_, v| v >= LEVELS_INDEX[level] }.keys
       end
 
       def excluded_levels
-        LEVELS.select { |_, v| v < LEVELS[level] }.keys
+        LEVELS_INDEX.select { |_, v| v < LEVELS_INDEX[level] }.keys
       end
     end
   end

data/lib/jazzy/source_declaration/type.rb

@@ -456,6 +456,10 @@ module Jazzy
           jazzy: 'Associated Type',
           dash: 'Alias',
         }.freeze,
+        'source.lang.swift.decl.macro' => {
+          jazzy: 'Macro',
+          dash: 'Macro',
+        }.freeze,
       }.freeze
     end
     # rubocop:enable Metrics/ClassLength

data/lib/jazzy/sourcekitten.rb

@@ -458,6 +458,13 @@ module Jazzy
       attrs.map { |str| str.gsub(/\)(?!\s*$)/, "\ufe5a") }
     end
 
+    # Keep everything except instructions to us
+    def self.extract_documented_attributes(declaration)
+      extract_attributes(declaration).reject do |attr|
+        attr.start_with?('@_documentation')
+      end
+    end
+
     def self.extract_availability(declaration)
       extract_attributes(declaration, 'available')
     end
@@ -521,7 +528,7 @@ module Jazzy
 
       # @available attrs only in compiler 'interface' style
       extract_availability(doc['key.doc.declaration'] || '')
-        .concat(extract_attributes(annotated_decl_attrs))
+        .concat(extract_documented_attributes(annotated_decl_attrs))
         .push(decl)
         .join("\n")
     end
@@ -603,6 +610,14 @@ module Jazzy
             "for `#{declaration.type.kind}`."
         end
 
+        unless documented_name
+          warn 'Found a declaration without `key.name` that will be ' \
+            'ignored.  Documentation may be incomplete.  This is probably ' \
+            'caused by unresolved compiler errors: check the sourcekitten ' \
+            'output for error messages.'
+          next
+        end
+
         declaration.file = Pathname(doc['key.filepath']) if doc['key.filepath']
         declaration.usr = doc['key.usr']
         declaration.type_usr = doc['key.typeusr']

data/lib/jazzy/stats.rb

@@ -41,7 +41,7 @@ module Jazzy
     end
 
     def report
-      puts "#{doc_coverage}\% documentation coverage " \
+      puts "#{doc_coverage}% documentation coverage " \
         "with #{undocumented} undocumented " \
         "#{symbol_or_symbols(undocumented)}"
 

data/lib/jazzy/symbol_graph/constraint.rb

@@ -70,8 +70,13 @@ module Jazzy
         end.compact
       end
 
-      # Workaround Swift 5.3 bug with missing constraint rels
+      # Workaround Swift 5.3 bug with missing constraint rels, eg.
+      # extension P {
+      #   func f<C>(a: C) where C: P {}
+      # }
       def self.new_list_from_declaration(decl)
+        return [] if decl.include?('(')
+
         decl.split(/\s*,\s*/).map { |cons| Constraint.new_declaration(cons) }
       end
 

data/lib/jazzy/symbol_graph/symbol.rb

@@ -100,6 +100,7 @@ module Jazzy
         'typealias' => 'typealias',
         'associatedtype' => 'associatedtype',
         'actor' => 'actor',
+        'macro' => 'macro',
       }.freeze
 
       # We treat 'static var' differently to 'class var'
@@ -110,7 +111,7 @@ module Jazzy
         end
         return kind unless keywords.member?('static')
 
-        kind.gsub(/type/, 'static')
+        kind.gsub('type', 'static')
       end
 
       def init_kind(kind, keywords)

data/lib/jazzy/symbol_graph.rb

@@ -68,7 +68,7 @@ module Jazzy
 
     # Parse the symbol files in the given directory
     def self.parse_symbols(directory)
-      Dir[directory + '/*.symbols.json'].map do |filename|
+      Dir[directory + '/*.symbols.json'].sort.map do |filename|
         # The @ part is for extensions in our module (before the @)
         # of types in another module (after the @).
         File.basename(filename) =~ /(.*?)(@(.*?))?\.symbols/