45978435e7
- Previously I thought that comments were fine to discourage people from wasting their time trying to bump things that used `undef` that Sorbet didn't support. But RuboCop is better at this since it'll complain if the comments are unnecessary. - Suggested in https://github.com/Homebrew/brew/pull/18018#issuecomment-2283369501. - I've gone for a mixture of `rubocop:disable` for the files that can't be `typed: strict` (use of undef, required before everything else, etc) and `rubocop:todo` for everything else that should be tried to make strictly typed. There's no functional difference between the two as `rubocop:todo` is `rubocop:disable` with a different name. - And I entirely disabled the cop for the docs/ directory since `typed: strict` isn't going to gain us anything for some Markdown linting config files. - This means that now it's easier to track what needs to be done rather than relying on checklists of files in our big Sorbet issue: ```shell $ git grep 'typed: true # rubocop:todo Sorbet/StrictSigil' | wc -l 268 ``` - And this is confirmed working for new files: ```shell $ git status On branch use-rubocop-for-sorbet-strict-sigils Untracked files: (use "git add <file>..." to include in what will be committed) Library/Homebrew/bad.rb Library/Homebrew/good.rb nothing added to commit but untracked files present (use "git add" to track) $ brew style Offenses: bad.rb:1:1: C: Sorbet/StrictSigil: Sorbet sigil should be at least strict got true. ^^^^^^^^^^^^^ 1340 files inspected, 1 offense detected ```
100 lines
3.8 KiB
Ruby
100 lines
3.8 KiB
Ruby
# typed: true # rubocop:todo Sorbet/StrictSigil
|
|
# frozen_string_literal: true
|
|
|
|
# from https://github.com/lsegal/yard/issues/484#issuecomment-442586899
|
|
module Homebrew
|
|
module YARD
|
|
class DocstringParser < ::YARD::DocstringParser
|
|
# Every `Object` has these methods.
|
|
OVERRIDABLE_METHODS = [
|
|
:hash, :inspect, :to_s,
|
|
:<=>, :===, :!~, :eql?, :equal?, :!, :==, :!=
|
|
].freeze
|
|
private_constant :OVERRIDABLE_METHODS
|
|
|
|
SELF_EXPLANATORY_METHODS = [:to_yaml, :to_json, :to_str].freeze
|
|
private_constant :SELF_EXPLANATORY_METHODS
|
|
|
|
def parse_content(content)
|
|
# Convert plain text to tags.
|
|
content = content&.gsub(/^\s*(TODO|FIXME):\s*/i, "@todo ")
|
|
content = content&.gsub(/^\s*NOTE:\s*/i, "@note ")
|
|
|
|
# Ignore non-documentation comments.
|
|
content = content&.sub(/\A(typed|.*rubocop):.*/m, "")
|
|
|
|
content = super
|
|
|
|
source = handler&.statement&.source
|
|
|
|
if object&.type == :method &&
|
|
(match = source&.match(/\so(deprecated|disabled)\s+"((?:\\"|[^"])*)"(?:\s*,\s*"((?:\\"|[^"])*))?"/m))
|
|
type = match[1]
|
|
method = match[2]
|
|
method = method.sub(/\#{self(\.class)?}/, object.namespace.to_s)
|
|
replacement = match[3]
|
|
replacement = replacement.sub(/\#{self(\.class)?}/, object.namespace.to_s)
|
|
|
|
# Only match `odeprecated`/`odisabled` for this method.
|
|
if method.match?(/(.|#|`)#{Regexp.escape(object.name.to_s)}`/)
|
|
if (method_name = method[/\A`([^`]*)`\Z/, 1]) && (
|
|
(method_name.count(".") + method_name.count("#")) <= 1
|
|
)
|
|
method_name = method_name.delete_prefix(object.namespace.to_s)
|
|
method = (method_name.delete_prefix(".") == object.name(true).to_s) ? nil : "{#{method_name}}"
|
|
end
|
|
|
|
if replacement &&
|
|
(replacement_method_name = replacement[/\A`([^`]*)`\Z/, 1]) && (
|
|
(replacement_method_name.count(".") + replacement_method_name.count("#")) <= 1
|
|
)
|
|
replacement_method_name = replacement_method_name.delete_prefix(object.namespace.to_s)
|
|
replacement = "{#{replacement_method_name}}"
|
|
end
|
|
|
|
if method && !method.include?('#{')
|
|
description = "Calling #{method} is #{type}"
|
|
description += ", use #{replacement} instead" if replacement && !replacement.include?('#{')
|
|
description += "."
|
|
elsif replacement && !replacement.include?('#{')
|
|
description = "Use #{replacement} instead."
|
|
else
|
|
description = ""
|
|
end
|
|
|
|
tags << create_tag("deprecated", description)
|
|
end
|
|
end
|
|
|
|
api = tags.find { |tag| tag.tag_name == "api" }&.text
|
|
is_private = tags.any? { |tag| tag.tag_name == "private" }
|
|
visibility = directives.find { |d| d.tag.tag_name == "visibility" }&.tag&.text
|
|
|
|
# Hide `#hash`, `#inspect` and `#to_s`.
|
|
if visibility.nil? && OVERRIDABLE_METHODS.include?(object&.name)
|
|
create_directive("visibility", "private")
|
|
visibility = "private"
|
|
end
|
|
|
|
# Mark everything as `@api private` by default.
|
|
if api.nil? && !is_private
|
|
tags << create_tag("api", "private")
|
|
api = "private"
|
|
end
|
|
|
|
# Warn about undocumented non-private APIs.
|
|
if handler && api && api != "private" && visibility != "private" &&
|
|
content.chomp.empty? && !SELF_EXPLANATORY_METHODS.include?(object&.name)
|
|
stmt = handler.statement
|
|
log.warn "#{api.capitalize} API should be documented:\n " \
|
|
"in `#{handler.parser.file}`:#{stmt.line}:\n\n#{stmt.show}\n"
|
|
end
|
|
|
|
content
|
|
end
|
|
end
|
|
end
|
|
end
|
|
|
|
YARD::Docstring.default_parser = Homebrew::YARD::DocstringParser
|