Merge pull request #1041 from realm/jf-unavailable

Mark unavailable and deprecated symbols in ObjC

CHANGELOG.md

@@ -10,6 +10,11 @@
   [John Fairhurst](https://github.com/johnfairh)
   [#730](https://github.com/realm/jazzy/issues/730)
 
+* Call out unavailable and deprecated Objective-C declarations.  
+  [Stefan Kieleithner](https://github.com/steviki)
+  [John Fairhurst](https://github.com/johnfairh)
+  [#843](https://github.com/realm/jazzy/issues/843)
+
 ##### Bug Fixes
 
 * Support Swift 4.2 with `--podspec`.  

lib/jazzy/doc_builder.rb

@@ -331,6 +331,7 @@ def self.gh_token_url(item, source_module)
     # Build mustache item for a top-level doc
     # @param [Hash] item Parsed doc child item
     # @param [Config] options Build options
+    # rubocop:disable Metrics/MethodLength
     def self.render_item(item, source_module)
       # Combine abstract and discussion into abstract
       abstract = (item.abstract || '') + (item.discussion || '')
@@ -350,8 +351,12 @@ def self.render_item(item, source_module)
         start_line:                 item.start_line,
         end_line:                   item.end_line,
         direct_link:                item.omit_content_from_parent?,
+        deprecation_message:        item.deprecation_message,
+        unavailable_message:        item.unavailable_message,
+        usage_discouraged:          item.usage_discouraged?,
       }
     end
+    # rubocop:enable Metrics/MethodLength
 
     def self.make_task(mark, uid, items)
       {
@@ -418,6 +423,9 @@ def self.document(source_module, doc_model, path_to_root)
       doc[:github_url] = source_module.github_url
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
+      doc[:deprecation_message] = doc_model.deprecation_message
+      doc[:unavailable_message] = doc_model.unavailable_message
+      doc[:usage_discouraged] = doc_model.usage_discouraged?
       doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
     end
     # rubocop:enable Metrics/MethodLength

lib/jazzy/source_declaration.rb

@@ -102,6 +102,14 @@ def display_other_language_declaration
     attr_accessor :end_line
     attr_accessor :nav_order
     attr_accessor :url_name
+    attr_accessor :deprecated
+    attr_accessor :deprecation_message
+    attr_accessor :unavailable
+    attr_accessor :unavailable_message
+
+    def usage_discouraged?
+      unavailable || deprecated
+    end
 
     def alternative_abstract
       if file = alternative_abstract_file

lib/jazzy/sourcekitten.rb

@@ -322,6 +322,8 @@ def self.make_doc_info(doc, declaration)
           Highlighter.highlight(make_swift_declaration(doc, declaration))
       end
 
+      make_deprecation_info(doc, declaration)
+
       unless doc['key.doc.full_as_xml']
         return process_undocumented_token(doc, declaration)
       end
@@ -335,6 +337,17 @@ def self.make_doc_info(doc, declaration)
       @stats.add_documented
     end
 
+    def self.make_deprecation_info(doc, declaration)
+      if declaration.deprecated
+        declaration.deprecation_message =
+          Markdown.render(doc['key.deprecation_message'] || '')
+      end
+      if declaration.unavailable
+        declaration.unavailable_message =
+          Markdown.render(doc['key.unavailable_message'] || '')
+      end
+    end
+
     # Strip tags and convert entities
     def self.xml_to_text(xml)
       document = REXML::Document.new(xml)
@@ -482,6 +495,8 @@ def self.make_source_declarations(docs, parent = nil, mark = SourceMark.new)
         declaration.column = doc['key.doc.column']
         declaration.start_line = doc['key.parsed_scope.start']
         declaration.end_line = doc['key.parsed_scope.end']
+        declaration.deprecated = doc['key.always_deprecated']
+        declaration.unavailable = doc['key.always_unavailable']
 
         next unless make_doc_info(doc, declaration)
         make_substructure(doc, declaration)
@@ -742,28 +757,34 @@ def self.autolink_text(text, doc, root_decls, after_highlight = false)
       end
     end
 
+    AUTOLINK_TEXT_FIELDS = %w[return
+                              abstract
+                              unavailable_message
+                              deprecation_message].freeze
+
+    AUTOLINK_HIGHLIGHT_FIELDS = %w[declaration
+                                   other_language_declaration].freeze
+
     def self.autolink(docs, root_decls)
       @autolink_root_decls = root_decls
       docs.each do |doc|
         doc.children = autolink(doc.children, root_decls)
 
-        doc.return = autolink_text(doc.return, doc, root_decls) if doc.return
-        doc.abstract = autolink_text(doc.abstract, doc, root_decls)
-        (doc.parameters || []).each do |param|
-          param[:discussion] =
-            autolink_text(param[:discussion], doc, root_decls)
+        AUTOLINK_TEXT_FIELDS.each do |field|
+          if text = doc.send(field)
+            doc.send(field + '=', autolink_text(text, doc, root_decls))
+          end
         end
 
-        if doc.declaration
-          doc.declaration = autolink_text(
-            doc.declaration, doc, root_decls, true
-          )
+        AUTOLINK_HIGHLIGHT_FIELDS.each do |field|
+          if text = doc.send(field)
+            doc.send(field + '=', autolink_text(text, doc, root_decls, true))
+          end
         end
 
-        if doc.other_language_declaration
-          doc.other_language_declaration = autolink_text(
-            doc.other_language_declaration, doc, root_decls, true
-          )
+        (doc.parameters || []).each do |param|
+          param[:discussion] =
+            autolink_text(param[:discussion], doc, root_decls)
         end
       end
     end

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

@@ -338,6 +338,9 @@ header {
     margin-left: 15px;
     font-size: 11.9px;
   }
+  .discouraged {
+    text-decoration: line-through;
+  }
   .declaration-note {
     font-size: .85em;
     color: rgba(128,128,128,1);
@@ -412,7 +415,7 @@ header {
   }
 }
 
-.aside-warning {
+.aside-warning, .aside-deprecated, .aside-unavailable {
   border-left: $aside_warning_border;
   .aside-title {
     color: $aside_warning_color;

lib/jazzy/themes/apple/templates/deprecation.mustache

@@ -0,0 +1,12 @@
+{{#deprecation_message}}
+<div class="aside aside-deprecated">
+  <p class="aside-title">Deprecated</p>
+  {{{deprecation_message}}}
+</div>
+{{/deprecation_message}}
+{{#unavailable_message}}
+<div class="aside aside-unavailable">
+  <p class="aside-title">Unavailable</p>
+  {{{unavailable_message}}}
+</div>
+{{/unavailable_message}}

lib/jazzy/themes/apple/templates/doc.mustache

@@ -28,6 +28,7 @@
         <section>
           <section class="section">
             {{^hide_name}}<h1>{{name}}</h1>{{/hide_name}}
+            {{> deprecation}}
             {{#declaration}}
               <div class="declaration">
                 <div class="language">

lib/jazzy/themes/apple/templates/task.mustache

@@ -20,7 +20,12 @@
         </code>
         {{/direct_link}}
         {{^direct_link}}
+        {{^usage_discouraged}}
         <a class="token" href="#/{{usr}}">{{name}}</a>
+        {{/usage_discouraged}}
+        {{#usage_discouraged}}
+        <a class="token discouraged" href="#/{{usr}}">{{name}}</a>
+        {{/usage_discouraged}}
         </code>
         {{#default_impl_abstract}}
           <span class="declaration-note">
@@ -37,6 +42,7 @@
         <div class="pointer-container"></div>
         <section class="section">
           <div class="pointer"></div>
+          {{> deprecation}}
           {{#abstract}}
           <div class="abstract">
             {{{abstract}}}

lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss

@@ -154,8 +154,14 @@ a {
     outline: 0;
     text-decoration: underline;
   }
-}
 
+  &.discouraged {
+    text-decoration: line-through;
+    &:hover, &:focus {
+      text-decoration: underline line-through;
+    }
+  }
+}
 
 // ----- Tables
 
@@ -479,7 +485,7 @@ pre code {
   }
 }
 
-.aside-warning {
+.aside-warning, .aside-deprecated, .aside-unavailable {
   border-left: $aside_warning_border;
   .aside-title {
     color: $aside_warning_color;

lib/jazzy/themes/fullwidth/templates/deprecation.mustache

@@ -0,0 +1,12 @@
+{{#deprecation_message}}
+<div class="aside aside-deprecated">
+  <p class="aside-title">Deprecated</p>
+  {{{deprecation_message}}}
+</div>
+{{/deprecation_message}}
+{{#unavailable_message}}
+<div class="aside aside-unavailable">
+  <p class="aside-title">Unavailable</p>
+  {{{unavailable_message}}}
+</div>
+{{/unavailable_message}}

lib/jazzy/themes/fullwidth/templates/doc.mustache

@@ -37,6 +37,7 @@
         <section class="section">
           <div class="section-content">
             {{^hide_name}}<h1>{{name}}</h1>{{/hide_name}}
+            {{> deprecation}}
             {{#declaration}}
               <div class="declaration">
                 <div class="language">

lib/jazzy/themes/fullwidth/templates/task.mustache

@@ -20,7 +20,12 @@
         </code>
         {{/direct_link}}
         {{^direct_link}}
+        {{^usage_discouraged}}
         <a class="token" href="#/{{usr}}">{{name}}</a>
+        {{/usage_discouraged}}
+        {{#usage_discouraged}}
+        <a class="token discouraged" href="#/{{usr}}">{{name}}</a>
+        {{/usage_discouraged}}
         </code>
         {{#default_impl_abstract}}
           <span class="declaration-note">
@@ -37,6 +42,7 @@
         <div class="pointer-container"></div>
         <section class="section">
           <div class="pointer"></div>
+          {{> deprecation}}
           {{#abstract}}
           <div class="abstract">
             {{{abstract}}}

lib/jazzy/themes/jony/assets/css/jazzy.css.scss

@@ -376,6 +376,9 @@ header {
     padding-left: 3px;
     margin-left: 35px;
   }
+  .discouraged {
+    text-decoration: line-through;
+  }
   .declaration-note {
     font-size: .85em;
     color: rgba(128,128,128,1);
@@ -448,7 +451,7 @@ header {
   }
 }
 
-.aside-warning {
+.aside-warning, .aside-deprecated, .aside-unavailable {
   border-left: $aside_warning_border;
   .aside-title {
     color: $aside_warning_color;

lib/jazzy/themes/jony/templates/deprecation.mustache

@@ -0,0 +1,12 @@
+{{#deprecation_message}}
+<div class="aside aside-deprecated">
+  <p class="aside-title">Deprecated</p>
+  {{{deprecation_message}}}
+</div>
+{{/deprecation_message}}
+{{#unavailable_message}}
+<div class="aside aside-unavailable">
+  <p class="aside-title">Unavailable</p>
+  {{{unavailable_message}}}
+</div>
+{{/unavailable_message}}

lib/jazzy/themes/jony/templates/doc.mustache

@@ -33,6 +33,7 @@
           <section>
             <section class="section">
               {{^hide_name}}<h1>{{name}}</h1>{{/hide_name}}
+              {{> deprecation}}
               {{#declaration}}
                 <div class="declaration">
                   <div class="language">

lib/jazzy/themes/jony/templates/task.mustache

@@ -20,7 +20,12 @@
         </code>
         {{/direct_link}}
         {{^direct_link}}
+        {{^usage_discouraged}}
         <a class="token" href="#/{{usr}}">{{name}}</a>
+        {{/usage_discouraged}}
+        {{#usage_discouraged}}
+        <a class="token discouraged" href="#/{{usr}}">{{name}}</a>
+        {{/usage_discouraged}}
         </code>
         {{#default_impl_abstract}}
           <span class="declaration-note">
@@ -37,6 +42,7 @@
         <div class="pointer-container"></div>
         <section class="section">
           <div class="pointer"></div>
+          {{> deprecation}}
           {{#abstract}}
           <div class="abstract">
             {{{abstract}}}