sord 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfebf9f7b35b936d5a448430b99c0aaa79cb13af0183cdf438c9d210b79fcbe4
-  data.tar.gz: fd5d9f369fbc55d34bac6b3338cb481a3a0a3ed748d47130327f841e5ac3d8a7
+  metadata.gz: ca2e726bf2e1ec8e4baa524ae7111296a18068d1a5d63959abc967bcc01b2651
+  data.tar.gz: 6e71373e3eb57ed98395aa0ecca42a5da3cd45ae5212712de151230f0cfa0870
 SHA512:
-  metadata.gz: 0407ed5b5770dd46c40df84dd40ba598d650a237f5f5a59127c66d30078970b36c803165dccbb9c6057784bee7763031f15d081fb0aabede6d100d5e943acd10
-  data.tar.gz: '07849f1278d3d40a3230c45293bc23d6c5ab31360f1d43a55ebc04eefc448e80481fc740180a776d6d999193798a30e1aa961a406c77e9f92d998a67ae43c4e2'
+  metadata.gz: 04c0bc1d1b2a74d5d428530cfafe9d21686be9d2bfb032379e7a705478f16ba53c027d85736d4f378104bb443d99706feca733ee1d465b2bf59200bfc61dbd70
+  data.tar.gz: 11a6fab0f1bd64e0c3b454bfa4c32ec84cc36b9f7dc2d30d726ab950e1091a0a53328b81666d3767adde2b6ff733af46647e4129a747a15f55db9a39227df8e9

data/CHANGELOG.md

@@ -3,6 +3,17 @@ 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/).
 
+## [0.10.0] - 2019-09-14
+### Added
+- Comments in RBIs are now converted from YARD into Markdown format, making them
+look much better when viewed in an IDE. (To restore the old behaviour of copying
+the YARD comments verbatim, use the `--keep-original-comments` flag.)
+
+### Changed
+- Parlour 0.8.0 is now being used.
+- References to `self` as a type in YARD docs are now generated as
+`T.self_type`, rather than a fixed self type determined by Sord.
+
 ## [0.9.0] - 2019-08-09
 ### Added
 - Add the `--replace-constants-with-untyped` flag, which generates `T.untyped` instead of `SORD_ERROR` constants.

data/README.md

@@ -52,8 +52,9 @@ where the maintainer is unwilling to ship type signatures with the gem itself.
 
 Sord also takes some flags to alter the generated `.rbi` file:
 
-  - `--no-comments`: Generates the `.rbi` file without any comments about
-    warnings/inferences/errors.
+  - `--no-sord-comments`: Generates the `.rbi` file without any Sord comments 
+    about warnings/inferences/errors. (The original file's comments will still
+    be included.)
   - `--no-regenerate`: By default, Sord will regenerate a repository's YARD
     docs for you. This option skips regenerating the YARD docs.
   - `--break-params`: Determines how many parameters are necessary before
@@ -76,22 +77,22 @@ Say we have this file, called `test.rb`:
 ```ruby
 module Example
   class Person
-    # @param [String] name
-    # @param [Integer] age
+    # @param name [String] The name of the Person to create.
+    # @param age [Integer] The age of the Person to create.
     # @return [Example::Person]
     def initialize(name, age)
       @name = name
       @age = age
     end
 
-    # @return [String] name
+    # @return name [String]
     attr_accessor :name
 
-    # @return [Integer] age
+    # @return age [Integer]
     attr_accessor :age
 
-    # @param [Array<String>] possible_names
-    # @param [Array<Integer>] possible_ages
+    # @param possible_names [Array<String>] An array of potential names to choose from.
+    # @param possible_ages [Array<Integer>] An array of potential ages to choose from.
     # @return [Example::Person]
     def self.construct_randomly(possible_names, possible_ages)
       Person.new(possible_names.sample, possible_ages.sample)
@@ -116,23 +117,27 @@ The `test.rbi` file then contains a complete RBI file for `test.rb`:
 # typed: strong
 module Example
   class Person
+    # @param `name` — The name of the Person to create.
+    # @param `age` — The age of the Person to create.
     sig { params(name: String, age: Integer).returns(Example::Person) }
     def initialize(name, age); end
 
     sig { returns(String) }
-    def name(); end
+    def name; end
 
     # sord infer - inferred type of parameter "value" as String using getter's return type
     sig { params(value: String).returns(String) }
     def name=(value); end
 
     sig { returns(Integer) }
-    def age(); end
+    def age; end
 
     # sord infer - inferred type of parameter "value" as Integer using getter's return type
     sig { params(value: Integer).returns(Integer) }
     def age=(value); end
 
+    # @param `possible_names` — An array of potential names to choose from.
+    # @param `possible_ages` — An array of potential ages to choose from.
     sig { params(possible_names: T::Array[String], possible_ages: T::Array[Integer]).returns(Example::Person) }
     def self.construct_randomly(possible_names, possible_ages); end
   end

data/Rakefile

@@ -45,7 +45,7 @@ namespace :examples do
         # Generate sri
         puts "Generating rbi for #{name}..."
         if args[:clean]
-          system("bundle exec sord ../#{name}.rbi --no-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
+          system("bundle exec sord ../#{name}.rbi --no-sord-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
         else
           system("bundle exec sord ../#{name}.rbi")
         end
@@ -70,7 +70,7 @@ namespace :examples do
       puts "Regenerating rbi file for #{name}..."
       Bundler.with_clean_env do
         if args[:clean]
-          system("bundle exec sord ../#{name}.rbi --no-regenerate --no-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
+          system("bundle exec sord ../#{name}.rbi --no-regenerate --no-sord-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
         else
           system("bundle exec sord ../#{name}.rbi --no-regenerate")
         end

data/exe/sord

@@ -11,23 +11,25 @@ default_command :gen
 command :gen do |c|
   c.syntax = 'sord gen <output-file> [options]'
   c.description = 'Generates an RBI file from this directory\'s YARD docs'
-  c.option '--[no-]comments', 'Controls informational/warning comments in the RBI file'
+  c.option '--[no-]sord-comments', 'Controls informational/warning comments in the RBI file'
   c.option '--[no-]regenerate', 'Controls whether YARD is executed before Sord runs'
   c.option '--break-params INTEGER', Integer, 'Break params onto their own lines if there are this many'
   c.option '--replace-errors-with-untyped', 'Uses T.untyped rather than SORD_ERROR_ constants'
   c.option '--replace-unresolved-with-untyped', 'Uses T.untyped when Sord is unable to resolve a constant'
   c.option '--exclude-messages STRING', String, 'Blacklists a comma-separated string of log message types'
   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.action do |args, options|
     options.default(
-      comments: true,
+      sord_comments: true,
       regenerate: true,
       break_params: 4,
       replace_errors_with_untyped: false,
       replace_unresolved_with_untyped: false,
       exclude_messages: nil,
       include_messages: nil,
+      keep_original_comments: false
     )
 
     if args.length != 1

data/lib/sord/parlour_plugin.rb

@@ -10,7 +10,7 @@ module Sord
       @parlour = nil
       @options = options
 
-      options[:comments] = true if options[:comments].nil?
+      options[:sord_comments] = true if options[:sord_comments].nil?
       options[:regenerate] = true if options[:regenerate].nil?
       options[:replace_errors_with_untyped] ||= false
       options[:replace_unresolved_with_untyped] ||= false

data/lib/sord/rbi_generator.rb

@@ -38,11 +38,12 @@ module Sord
 
       @replace_errors_with_untyped = options[:replace_errors_with_untyped]
       @replace_unresolved_with_untyped = options[:replace_unresolved_with_untyped]
+      @keep_original_comments = options[:keep_original_comments]
 
       # Hook the logger so that messages are added as comments to the RBI file
       Logging.add_hook do |type, msg, item|
         @current_object.add_comment_to_next_child("sord #{type} - #{msg}")
-      end if options[:comments]
+      end if options[:sord_comments]
 
       # Hook the logger so that warnings are collected
       Logging.add_hook do |type, msg, item|
@@ -88,7 +89,9 @@ module Sord
         constant_name = constant.to_s.split('::').last
         
         # Add the constant to the current object being generated.
-        @current_object.create_constant(constant_name, value: "T.let(#{constant.value}, T.untyped)")
+        @current_object.create_constant(constant_name, value: "T.let(#{constant.value}, T.untyped)") do |c|
+          c.add_comments(constant.docstring.all.split("\n"))
+        end
       end
     end
 
@@ -158,8 +161,13 @@ module Sord
               end
             end
 
+            return_types = getter.tags('return').flat_map(&:types)
+            unless return_types.any?
+              Logging.omit("no YARD type given for #{name.inspect}, using T.untyped", meth)
+              next 'T.untyped'
+            end
             inferred_type = TypeConverter.yard_to_sorbet(
-              getter.tags('return').flat_map(&:types), meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
+              return_types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
             
             Logging.infer("inferred type of parameter #{name.inspect} as #{inferred_type} using getter's return type", meth)
             inferred_type
@@ -209,7 +217,89 @@ module Sord
           parameters: parlour_params,
           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?
+                docs_array << "_@param_ `#{param.name}`"
+              else
+                docs_array << "_@param_ `#{param.name}` — #{param.text}"
+              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
+
+            m.add_comments(docs_array)
+          end
+        end
       end
     end
 
@@ -227,6 +317,7 @@ module Sord
       @current_object = item.type == :class \
         ? parent.create_class(item.name.to_s, superclass: superclass)
         : parent.create_module(item.name.to_s)
+      @current_object.add_comments(item.docstring.all.split("\n"))
 
       add_mixins(item)
       add_methods(item)

data/lib/sord/type_converter.rb

@@ -107,7 +107,7 @@ module Sord
       when  "bool", "Bool", "boolean", "Boolean", "true", "false"
         "T::Boolean"
       when 'self'
-        item.parent.path
+        'T.self_type'
       when Array
         # If there's only one element, unwrap it, otherwise allow for a
         # selection of any of the types

data/lib/sord/version.rb

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

data/sord.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'yard'
   spec.add_dependency 'sorbet-runtime'
   spec.add_dependency 'commander', '~> 4.4'
-  spec.add_dependency 'parlour', '~> 0.6.1'
+  spec.add_dependency 'parlour', '~> 0.8.0'
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sord
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-08-09 00:00:00.000000000 Z
+date: 2019-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement