sord 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86ef36c437c7c9a02b0cc18fddd6c11253f4d0be6f9d68283c8039cfd69d310e
-  data.tar.gz: 38f53748c92a22b44745d8fff1dfca5fe41ee4b4424b3c61c63853d07eb5d396
+  metadata.gz: 14900bd9ce64eda2373d0844e42032ea041b44dd10a6ca6a82bd66c31b2b0c9b
+  data.tar.gz: 983e467e872f0e455da6ca618b2a2ffb159d81f6cc1456e8370e33ecd42179bf
 SHA512:
-  metadata.gz: 3359eca2a431b010b81c9920f6dd2705422df7ee3b47ab014caf63d498168945e14e5b3ba789ab08dff2b1a081682ae0d05de3c1796d2ac948778ca1a8a8c9c5
-  data.tar.gz: 92ef1253541f9d4a837486fe51a886341251db0acc145d224048e8e3d94368beb86e59edab5a3638e486bb877f65a188da38c1543a2708cac10b14eef81e5da1
+  metadata.gz: 6a63ef228f6763653b2be68d46c16f20793118a67adec93d6cc2ec016ed9df254803e3b1fb1bc5c5b26a248020715ee72836c3b4fab6bb07e2d1223e685af97b
+  data.tar.gz: b9a86b1af67cdfd6d73eb28f2b6b46d10b5e61418d2118693e2103da1d5e9d506c8046b069922b908d1d4ecd908abf832ad4a480868b6720650a386fb010d766

data/CHANGELOG.md

@@ -3,6 +3,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [2.0.0] - 2020-03-16
+### Added
+- Sord now supports generating `attr_accessor`, `attr_reader` and `attr_writer`
+and will do so automatically when these are used in your code.
+  - Depending on what you're doing with Sord, this is **potentially breaking**,
+  as for example attributes which would previously generate two `foo` and `foo=`
+  methods in Sord will now just generate an `attr_accessor`.
+- `#initialize` is now always typed as returning `void`, which is
+**potentially breaking** if you directly call `#initialize` in code.
+  - The `--use-original-initialize-return` flag restores the old behaviour of
+  using whatever return type is provided, like any other method.
+
 ## [1.0.0] - 2020-02-16
 ### Added
 - Added the `--skip-constants` flag to avoid generating RBIs for constants.

data/exe/sord

@@ -20,6 +20,7 @@ command :gen do |c|
   c.option '--include-messages STRING', String, 'Whitelists a comma-separated string of log message types'
   c.option '--keep-original-comments', 'Retains original YARD comments rather than converting them to Markdown'
   c.option '--skip-constants', 'Excludes constants from generated RBI'
+  c.option '--use-original-initialize-return', 'Uses the specified return type for #initialize rather than void'
 
   c.action do |args, options|
     options.default(
@@ -31,7 +32,8 @@ command :gen do |c|
       exclude_messages: nil,
       include_messages: nil,
       keep_original_comments: false,
-      skip_constants: false
+      skip_constants: false,
+      use_original_initialize_return: false,
     )
 
     if args.length != 1

data/lib/sord/rbi_generator.rb

@@ -40,6 +40,7 @@ module Sord
       @replace_unresolved_with_untyped = options[:replace_unresolved_with_untyped]
       @keep_original_comments = options[:keep_original_comments]
       @skip_constants = options[:skip_constants]
+      @use_original_initialize_return = options[:use_original_initialize_return]
 
       # Hook the logger so that messages are added as comments to the RBI file
       Logging.add_hook do |type, msg, item|
@@ -96,6 +97,97 @@ module Sord
       end
     end
 
+    # Adds comments to an RBI object based on a docstring.
+    # @param [YARD::CodeObjects::NamespaceObject] item
+    # @param [Parlour::RbiGenerator::RbiObject] rbi_object
+    # @return [void]
+    def add_comments(item, rbi_object)
+      if @keep_original_comments
+        rbi_object.add_comments(item.docstring.all.split("\n"))
+      else
+        parser = YARD::Docstring.parser
+        parser.parse(item.docstring.all)
+
+        docs_array = parser.text.split("\n")
+
+        # Add @param tags if there are any with names and descriptions.
+        params = parser.tags.select { |tag| tag.tag_name == 'param' && tag.is_a?(YARD::Tags::Tag) && !tag.name.nil? }
+        # Add a blank line if there's anything before the params.
+        docs_array << '' if docs_array.length.positive? && params.length.positive?
+        params.each do |param|
+          docs_array << '' if docs_array.last != '' && docs_array.length.positive?
+          # Output params in the form of:
+          # _@param_ `foo` — Lorem ipsum.
+          # _@param_ `foo`
+          if param.text.nil? || param.text == ''
+            docs_array << "_@param_ `#{param.name}`"
+          else
+            docs_array << "_@param_ `#{param.name}` — #{param.text.gsub("\n", " ")}"
+          end
+        end
+
+        # Add @return tags (there could possibly be more than one, despite this not being supported)
+        returns = parser.tags.select { |tag| tag.tag_name == 'return' && tag.is_a?(YARD::Tags::Tag) && !tag.text.nil? && tag.text.strip != '' }
+        # Add a blank line if there's anything before the returns.
+        docs_array << '' if docs_array.length.positive? && returns.length.positive?
+        returns.each do |retn|
+          docs_array << '' if docs_array.last != '' && docs_array.length.positive?
+          # Output returns in the form of:
+          # _@return_ — Lorem ipsum.
+          docs_array << "_@return_ — #{retn.text}"
+        end
+
+        # Iterate through the @example tags for a given YARD doc and output them in Markdown codeblocks.
+        examples = parser.tags.select { |tag| tag.tag_name == 'example' && tag.is_a?(YARD::Tags::Tag) }
+        examples.each do |example|
+          # Only add a blank line if there's anything before the example.
+          docs_array << '' if docs_array.length.positive?
+          # Include the example's 'name' if there is one.
+          docs_array << example.name unless example.name.nil? || example.name == ""
+          docs_array << "```ruby"
+          docs_array.concat(example.text.split("\n"))
+          docs_array << "```"
+        end if examples.length.positive?
+
+        # Add @note and @deprecated tags.
+        notice_tags = parser.tags.select { |tag| ['note', 'deprecated'].include?(tag.tag_name) && tag.is_a?(YARD::Tags::Tag) }
+        # Add a blank line if there's anything before the params.
+        docs_array << '' if docs_array.last != '' && docs_array.length.positive? && notice_tags.length.positive?
+        notice_tags.each do |notice_tag|
+          docs_array << '' if docs_array.last != ''
+          # Output note/deprecated/see in the form of:
+          # _@note_ — Lorem ipsum.
+          # _@note_
+          if notice_tag.text.nil?
+            docs_array << "_@#{notice_tag.tag_name}_"
+          else
+            docs_array << "_@#{notice_tag.tag_name}_ — #{notice_tag.text}"
+          end
+        end
+
+        # Add @see tags.
+        see_tags = parser.tags.select { |tag| tag.tag_name == 'see' && tag.is_a?(YARD::Tags::Tag) }
+        # Add a blank line if there's anything before the params.
+        docs_array << '' if docs_array.last != '' && docs_array.length.positive? && see_tags.length.positive?
+        see_tags.each do |see_tag|
+          docs_array << '' if docs_array.last != ''
+          # Output note/deprecated/see in the form of:
+          # _@see_ `B` — Lorem ipsum.
+          # _@see_ `B`
+          if see_tag.text.nil?
+            docs_array << "_@see_ `#{see_tag.name}`"
+          else
+            docs_array << "_@see_ `#{see_tag.name}` — #{see_tag.text}"
+          end
+        end
+
+        # fix: yard text may contains multiple line. should deal \n.
+        # else generate text will be multiple line and only first line is commented
+        docs_array = docs_array.flat_map {|line| line.empty? ? [""] : line.split("\n")}
+        rbi_object.add_comments(docs_array)
+      end
+    end
+
     # Given a YARD NamespaceObject, add lines defining its methods and their
     # signatures to the current RBI file.
     # @param [YARD::CodeObjects::NamespaceObject] item
@@ -110,6 +202,11 @@ module Sord
           next
         end
 
+        # If the method is an attribute, it'll be handled by add_attributes
+        if meth.is_attribute?
+          next
+        end
+      
         # Sort parameters
         meth.parameters.reverse.sort! { |pair1, pair2| sort_params(pair1, pair2) }
         # This is better than iterating over YARD's "@param" tags directly 
@@ -191,7 +288,9 @@ module Sord
         end
 
         return_tags = meth.tags('return')
-        returns = if return_tags.length == 0
+        returns = if meth.name == :initialize && !@use_original_initialize_return
+          nil
+        elsif return_tags.length == 0
           Logging.omit("no YARD return type given, using T.untyped", meth)
           'T.untyped'
         elsif return_tags.length == 1 && return_tags&.first&.types&.first&.downcase == "void"
@@ -221,89 +320,65 @@ module Sord
           returns: returns,
           class_method: meth.scope == :class
         ) do |m|
-          if @keep_original_comments
-            m.add_comments(meth.docstring.all.split("\n"))
-          else
-            parser = YARD::Docstring.parser
-            parser.parse(meth.docstring.all)
-
-            docs_array = parser.text.split("\n")
-
-            # Add @param tags if there are any with names and descriptions.
-            params = parser.tags.select { |tag| tag.tag_name == 'param' && tag.is_a?(YARD::Tags::Tag) && !tag.name.nil? }
-            # Add a blank line if there's anything before the params.
-            docs_array << '' if docs_array.length.positive? && params.length.positive?
-            params.each do |param|
-              docs_array << '' if docs_array.last != '' && docs_array.length.positive?
-              # Output params in the form of:
-              # _@param_ `foo` — Lorem ipsum.
-              # _@param_ `foo`
-              if param.text.nil? || param.text == ''
-                docs_array << "_@param_ `#{param.name}`"
-              else
-                docs_array << "_@param_ `#{param.name}` — #{param.text.gsub("\n", " ")}"
-              end
-            end
+          add_comments(meth, m)
+        end
+      end
+    end
 
-            # Add @return tags (there could possibly be more than one, despite this not being supported)
-            returns = parser.tags.select { |tag| tag.tag_name == 'return' && tag.is_a?(YARD::Tags::Tag) && !tag.text.nil? && tag.text.strip != '' }
-            # Add a blank line if there's anything before the returns.
-            docs_array << '' if docs_array.length.positive? && returns.length.positive?
-            returns.each do |retn|
-              docs_array << '' if docs_array.last != '' && docs_array.length.positive?
-              # Output returns in the form of:
-              # _@return_ — Lorem ipsum.
-              docs_array << "_@return_ — #{retn.text}"
-            end
+    # Given a YARD NamespaceObject, add lines defining either its class
+    # and instance attributes and their signatures to the current RBI file.
+    # @param [YARD::CodeObjects::NamespaceObject] item
+    # @return [void]
+    def add_attributes(item)
+      [:class, :instance].each do |attr_loc|
+        # Grab attributes for the current location (class or instance)
+        attrs = item.attributes[attr_loc]
+        attrs.each do |name, attribute|
+          reader = attribute[:read]
+          writer = attribute[:write]
+
+          unless reader || writer
+            Logging.warn("attribute is not readable or writable somehow, skipping", attribute)
+            next
+          end
 
-            # Iterate through the @example tags for a given YARD doc and output them in Markdown codeblocks.
-            examples = parser.tags.select { |tag| tag.tag_name == 'example' && tag.is_a?(YARD::Tags::Tag) }
-            examples.each do |example|
-              # Only add a blank line if there's anything before the example.
-              docs_array << '' if docs_array.length.positive?
-              # Include the example's 'name' if there is one.
-              docs_array << example.name unless example.name.nil? || example.name == ""
-              docs_array << "```ruby"
-              docs_array.concat(example.text.split("\n"))
-              docs_array << "```"
-            end if examples.length.positive?
-
-            # Add @note and @deprecated tags.
-            notice_tags = parser.tags.select { |tag| ['note', 'deprecated'].include?(tag.tag_name) && tag.is_a?(YARD::Tags::Tag) }
-            # Add a blank line if there's anything before the params.
-            docs_array << '' if docs_array.last != '' && docs_array.length.positive? && notice_tags.length.positive?
-            notice_tags.each do |notice_tag|
-              docs_array << '' if docs_array.last != ''
-              # Output note/deprecated/see in the form of:
-              # _@note_ — Lorem ipsum.
-              # _@note_
-              if notice_tag.text.nil?
-                docs_array << "_@#{notice_tag.tag_name}_"
-              else
-                docs_array << "_@#{notice_tag.tag_name}_ — #{notice_tag.text}"
-              end
-            end
+          # Get all given types
+          yard_types = []
+          if reader
+            yard_types += reader.tags('return').flat_map(&:types).compact.reject { |x| x.downcase == 'void' } +
+              reader.tags('param').flat_map(&:types)
+          end
+          if writer
+            yard_types += writer.tags('return').flat_map(&:types).compact.reject { |x| x.downcase == 'void' } +
+              writer.tags('param').flat_map(&:types)
+          end
 
-            # Add @see tags.
-            see_tags = parser.tags.select { |tag| tag.tag_name == 'see' && tag.is_a?(YARD::Tags::Tag) }
-            # Add a blank line if there's anything before the params.
-            docs_array << '' if docs_array.last != '' && docs_array.length.positive? && see_tags.length.positive?
-            see_tags.each do |see_tag|
-              docs_array << '' if docs_array.last != ''
-              # Output note/deprecated/see in the form of:
-              # _@see_ `B` — Lorem ipsum.
-              # _@see_ `B`
-              if see_tag.text.nil?
-                docs_array << "_@see_ `#{see_tag.name}`"
-              else
-                docs_array << "_@see_ `#{see_tag.name}` — #{see_tag.text}"
-              end
-            end
+          # Use T.untyped if not types specified anywhere, otherwise try to
+          # compute Sorbet type given all these types
+          if yard_types.empty?
+            Logging.omit("no YARD type given for #{name.inspect}, using T.untyped", reader || writer)
+            sorbet_type = 'T.untyped'
+          else
+            sorbet_type = TypeConverter.yard_to_sorbet(
+              yard_types, reader || writer, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
+          end
+
+          # Generate attribute
+          if reader && writer
+            kind = :accessor
+          elsif reader
+            kind = :reader
+          elsif writer
+            kind = :writer
+          end
 
-            # fix: yard text may contains multiple line. should deal \n.
-            # else generate text will be multiple line and only first line is commented
-            docs_array = docs_array.flat_map {|line| line.empty? ? [""] : line.split("\n")}
-            m.add_comments(docs_array)
+          @current_object.create_attribute(
+            name.to_s,
+            kind: kind,
+            type: sorbet_type,
+            class_attribute: (attr_loc == :class)
+          ) do |m|
+            add_comments(reader || writer, m)
           end
         end
       end
@@ -327,6 +402,7 @@ module Sord
 
       add_mixins(item)
       add_methods(item)
+      add_attributes(item)
       add_constants(item) unless @skip_constants
 
       item.children.select { |x| [:class, :module].include?(x.type) }

data/lib/sord/version.rb

@@ -1,4 +1,4 @@
 # typed: strong
 module Sord
-  VERSION = '1.0.0'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sord
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-02-16 00:00:00.000000000 Z
+date: 2020-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -185,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Generate Sorbet RBI files from YARD documentation