rubocop-publicdoc2 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f47572451602f0cb28be0997c1626c0fcd218a60dbad8c0ca5edcd97ab093500
+  data.tar.gz: 071c9289b76dd2a4fb9cbb1cbfd979e664c52dd6e0926943549f7d86e104c691
+SHA512:
+  metadata.gz: 626e6be5fa81324b512397956b27659b66d8fff181d86dbaefeec6ec661ffd2779f28613124a42d9d91394508555af5ca15a27b912c634376557e58f95dbbc78
+  data.tar.gz: b00f1afad0dc06c87b3caa7bfc35fc253da7768aae1a2d0256b9f736233f97275eb120958efb6f3bf1ac642221a9df8ab4bba7e84308c2ad4308a2e5e360e208

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,3 @@
+Naming/FileName:
+ Exclude:
+   - lib/rubocop-publicdoc2.rb

data/.ruby-gemset

@@ -0,0 +1 @@
+rubocop-publicdoc2

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.6.8

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.8
+before_install: gem install bundler -v 2.0.2

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+## New features
+* Style/PublicMethodDocumentation

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at TODO: Write your email address. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+ruby '2.6.8'
+# Specify your gem's dependencies in rubocop-publicdoc2.gemspec
+gemspec
+# gem 'bundler', '~> 2.0'
+gem 'rake'
+gem 'rspec'

data/Gemfile.lock

@@ -0,0 +1,59 @@
+PATH
+  remote: .
+  specs:
+    rubocop-publicdoc2 (0.1.2)
+      rubocop
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.4.4)
+    parallel (1.20.1)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rubocop (1.20.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.9.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.11.0)
+      parser (>= 3.0.1.1)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.17.2)
+  rake
+  rspec
+  rubocop-publicdoc2!
+
+RUBY VERSION
+   ruby 2.6.8p205
+
+BUNDLED WITH
+   1.17.2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Paul Kristoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Paul Kristoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,43 @@
+# Rubocop::Publicdoc2
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rubocop/publicdoc2`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rubocop-publicdoc2', require: false
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rubocop-publicdoc2
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rubocop-publicdoc2. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Rubocop::Publicdoc2 project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rubocop-publicdoc2/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,34 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+desc 'Generate a new cop with a template'
+task :new_cop, [:cop] do |_task, args|
+  require 'rubocop'
+
+  cop_name = args.fetch(:cop) do
+    warn 'usage: bundle exec rake new_cop[Department/Name]'
+    exit!
+  end
+
+  github_user = `git config github.user`.chop
+  github_user = 'your_id' if github_user.empty?
+
+  generator = RuboCop::Cop::Generator.new(cop_name, github_user)
+
+  generator.write_source
+  generator.write_spec
+  generator.inject_require(root_file_path: 'lib/rubocop/cop/publicdoc2_cops.rb')
+  generator.inject_config(config_file_path: 'config/default.yml')
+
+  puts generator.todo
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rubocop/publicdoc2"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/config/default.yml

@@ -0,0 +1,17 @@
+# Write it!
+
+Style/PublicMethodDocumentation:
+  Description: 'check public methods to have correct documentation'
+  Enabled: pending
+  VersionAdded: '0.1.0'
+
+Style/PublicClassDocumentation:
+  Description: 'check classes have correct documentation'
+  Enabled: pending
+  VersionAdded: '0.1.0'
+
+# this added to allow tests to work
+Style/CommentAnnotation:
+  Keywords: []
+  Enabled: false
+

data/lib/rubocop/cop/publicdoc2_cops.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+require_relative 'style/public_method_documentation'
+require_relative 'style/public_class_documentation'

data/lib/rubocop/cop/style/public_class_documentation.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Style
+      # TODO: Write cop description and example of bad / good code. For every
+      # `SupportedStyle` and unique configuration, there needs to be examples.
+      # Examples must have valid Ruby syntax. Do not use upticks.
+      #
+      # @example EnforcedStyle: PublicClassDocumentation (default)
+      #   # Description of the `PublicClassDocumentation` style.
+      #
+      #   # bad
+      #   class xxx
+      #
+      #   # bad
+      #   # class xxx documentation
+      #   class xxx
+      #
+      #   # bad
+      #   # class xxx documentation
+      #   # the end
+      #   class xxx
+      #
+      #   # good
+      #   # class xxx documentation
+      #   #
+      #   class xxx
+      #
+      class PublicClassDocumentation < Documentation
+        # TODO: Implement the cop in here.
+        #
+        # In many cases, you can use a node matcher for matching node pattern.
+        # See https://github.com/rubocop/rubocop-ast/blob/master/lib/rubocop/ast/node_pattern.rb
+        #
+        # For example
+
+        # overide method to add on my class doc
+        #
+        # === Parameters:
+        #
+        # * <tt>:node</tt> a class node
+        #
+        def on_class(node)
+          check_class_comment(node, :class)
+          super
+        end
+
+        private
+
+        def check_class_comment(node, type)
+          if documentation_comment?(node)
+            add_offense(preceding_lines(node).last, message: 'Class documentation should end with an empty line') unless class_comment_blank?(node)
+          else
+            add_offense(node, message: 'Missing class documentation')
+          end
+        end
+
+        def class_comment_blank?(node)
+          # assumes a comment exists
+          last_line = preceding_lines(node).last
+          /^\#$/.match?(last_line.text)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/style/public_method_documentation.rb

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Style
+      # TODO: Write cop description and example of bad / good code. For every
+      # `SupportedStyle` and unique configuration, there needs to be examples.
+      # Examples must have valid Ruby syntax. Do not use upticks.
+      #
+      # @example EnforcedStyle: PublicMethodDocumentation (default)
+      #   # Description of the `PublicMethodDocumentation` style.
+      #
+      #   # bad
+      #   def xxx
+      #
+      #   # bad
+      #   # xxx documentation
+      #   def xxx
+      #
+      #   # bad
+      #   # xxx documentation
+      #   # the end
+      #   def xxx
+      #
+      #   # good
+      #   # class xxx documentation
+      #   #
+      #   def xxx
+      #
+      #   # bad
+      #   # class xxx documentation
+      #   #
+      #   def xxx(p1)
+      #
+      class PublicMethodDocumentation < DocumentationMethod
+        ATTRS_DOC = '# === Attributes:'
+        RETURNS_DOC = '# === Returns:'
+        PARMS_DOC = '# === Parameters:'
+
+        MSG_ATTRIBUTES_AND_PARAMETERS_NO_COEXIST = 'Attributes and Parameters should not exist on same method.'
+        MSG_DESCRIPTION_SHOULD_END_WITH_BLANK_COMMENT = 'Description should end with blank comment.'
+        MSG_MISSING_DOCUMENTATION = 'Missing public method documentation comment for `%s`.'
+        MSG_MISSING_PARAMETERS = 'Parameter is missing for `%s`.'
+        MSG_PARAMETERS_ARG_NAME_MISMATCH = 'Parameter name `%s` does not match argument name `%s`.'
+        MSG_PARAMETERS_ARG_SIZE_MISMATCH = 'Parameter size `%s` does not match argument size `%s`.'
+        MSG_PARAMETERS_SHOULD_BE_BEFORE_RETURNS = 'Parameters should be before Returns.'
+        MSG_RANGE_BODY_EMPTY = '%s body is empty.'
+        MSG_RETURNS_SHOULD_BE_LAST = 'Returns should be last.'
+
+        #   https://regex101.com/
+        ATTR_REGEXP = /^ *# *=== *Attributes:/.freeze
+        DOC_PARM_REGEXP = %r{^# \* <tt>:(\w+)</tt>}.freeze
+        DOC_RET_REGEXP = %r{^# \* <tt>([:\w]+)</tt>}.freeze
+        PARMS_REGEXP = /^ *# *=== *Parameters:/.freeze
+        RETURNS_REGEXP = /^ *# *=== *Returns: */.freeze
+
+        # TODO: Implement the cop in here.
+        #
+        # In many cases, you can use a node matcher for matching node pattern.
+        # See https://github.com/rubocop/rubocop-ast/blob/master/lib/rubocop/ast/node_pattern.rb
+        #
+        # For example
+        include DocumentationComment
+        include DefNode
+
+        # checks for public methods to make sure they have proper documentation
+        #   if not it will add an offense
+        #
+        # === Parameters:
+        #
+        # * <tt>:node</tt> a def node
+        #
+        def on_def(node)
+          # puts("start-#{node.children.first.to_s}")
+          check(node)
+          # puts 'end-on_def'
+        end
+
+        private
+
+        def add_format(message)
+          format(message, @method_name)
+        end
+
+        def add_offense(node, location: :expression, message: nil, severity: nil)
+          super(node, message: add_format(message), severity: severity)
+        end
+
+        def check(node)
+          return if non_public?(node)
+
+          # return if documentation_comment?(node)
+          prk_documentation_comment(node)
+        end
+
+        def prk_documentation_comment(node)
+          @method_name = node.children.first.to_s
+          # puts "  processing: #{@method_name}"
+          preceding_lines = preceding_lines(node)
+
+          return add_offense(node, message: MSG_MISSING_DOCUMENTATION) unless preceding_comment?(node, preceding_lines.last)
+
+          description_range, parameters_range, returns_range, attrs_range = parse_documentation(preceding_lines)
+
+          add_offense(preceding_lines[0], message: MSG_MISSING_DESCRIPTION) if description_range.nil?
+
+          # order
+          #   description_range
+          #   parameters_range || attrs_range
+          #   returns_range
+          #
+          grd = description_range.before?(parameters_range) &&
+            description_range.before?(returns_range) &&
+            description_range.before?(attrs_range)
+          add_offense(description_range.start_comment, message: MSG_DESCRIPTIION_SHOULD_BE_FIRST) unless grd
+          guard = parameters_range.before?(returns_range)
+          grd = guard && attrs_range.before?(returns_range)
+          add_offense(description_range.start_comment, message: MSG_RETURNS_SHOULD_BE_LAST) unless grd
+
+          grd = attrs_range.missing? || parameters_range.missing?
+          add_offense(attrs_range.start_comment, message: MSG_ATTRIBUTES_AND_PARAMETERS_NO_COEXIST) unless grd
+
+          special_comm = preceding_lines.any? do |comment|
+            !AnnotationComment.new(comment, annotation_keywords).annotation? &&
+              !interpreter_directive_comment?(comment) &&
+              !rubocop_directive_comment?(comment)
+          end
+
+          return add_offense(preceding_lines[index], message: MSG_INVALID_DOCUMENTATION) unless special_comm
+
+          add_offense(parameters_range.start_comment, message: MSG_PARAMETERS_SHOULD_BE_BEFORE_RETURNS) unless guard
+
+          check_blank_comments(description_range, parameters_range, returns_range, attrs_range)
+
+          args = node.arguments
+          guard = parameters_range.missing? && !args.empty?
+          return add_offense(preceding_lines[0], message: MSG_MISSING_PARAMETERS) if guard
+
+          guard = !parameters_range.missing? && args.empty?
+          return add_offense(parameters_range.start_comment, message: MSG_UNNECESSARY_PARAMETERS) if guard
+
+          check_body(parameters_range) unless parameters_range.missing?
+          check_body(attrs_range) unless attrs_range.missing?
+          check_body(returns_range) unless returns_range.missing?
+
+          check_parms_and_args(args, parameters_range) unless parameters_range.missing?
+        end
+
+        def parse_documentation(comments)
+          desc = MethodDocRange.new(comments, 'Description')
+          returns = MethodDocRange.new(comments, 'Return')
+          parms = MethodDocRange.new(comments, 'Parameter')
+          attrs = MethodDocRange.new(comments, 'Attribute')
+          current = nil
+          comments.each_with_index do |comment_line, i|
+            text_line = comment_line.text
+            if RETURNS_REGEXP.match?(text_line)
+              current.end = i - 1 unless current.nil?
+              returns.start = i # [comment_line, i, 0]
+              current = returns
+            elsif PARMS_REGEXP.match?(text_line)
+              current.end = i - 1 unless current.nil?
+              parms.start = i # [comment_line, i, 0]
+              current = parms
+            elsif ATTR_REGEXP.match?(text_line)
+              current.end = i - 1 unless current.nil?
+              attrs.start = i # [comment_line, i, 0]
+              current = attrs
+            elsif i == 0
+              current.end = i - 1 unless current.nil?
+              desc.start = i # [comment_line, i, 0]
+              current = desc
+            end
+            current.end = comments.size - 1
+          end
+          # !parms.first_comment? && !returns.first_comment?
+          add_offense(comments[0], message: MSG_MISSING_DESCRIPTION) if desc.missing?
+          unless parms.missing?
+            guard = parms.first_comment_equal?(PARMS_DOC)
+            add_offense(parms.start_comment, message: MSG_PARAMETERS_DOES_MATCH_MATCH) unless guard
+          end
+          unless returns.missing?
+            guard = returns.first_comment_equal?(RETURNS_DOC)
+            add_offense(returns.start_comment, message: MSG_RETURNS_DOES_NOT_MATCH) unless guard
+          end
+          unless attrs.missing?
+            add_offense(attrs.start_comment, message: MSG_RETURNS_DOES_NOT_MATCH) unless attrs.first_comment_equal?(ATTRS_DOC)
+          end
+          # puts 'parse_document result'
+          # puts("    desc =#{desc.to_s}")
+          # puts("    parms=#{parms.to_s}")
+          # puts("    returns=#{returns.to_s}")
+          # puts("    attrs=#{attrs.to_s}")
+          [desc, parms, returns, attrs]
+        end
+
+        def check_blank_comments(description_range, parameters_range, returns_range, attrs_range)
+          unless description_range.missing?
+            # rubocop:disable Layout/LineLength
+            add_offense(description_range.start_comment, message: MSG_DESCRIPTION_SHOULD_NOT_BEGIN_WITH_BLANK_COMMENT) if description_range.starts_with_empty_comment?
+            add_offense(description_range.end_comment, message: MSG_DESCRIPTION_SHOULD_END_WITH_BLANK_COMMENT) unless description_range.ends_with_empty_comment?
+          end
+
+          add_offense(parameters_range.start_comment, message: MSG_PARAMETERS_IS_MISSING_FIRST_BLANK_COMMENT) unless parameters_range.first_empty_comment?
+          add_offense(parameters_range.end_comment, message: MSG_PARAMETERS_SHOULD_END_WITH_BLANK_COMMENT) unless parameters_range.ends_with_empty_comment?
+
+          add_offense(returns_range.start_comment, message: MSG_RETURNS_IS_MISSING_FIRST_BLANK_COMMENT) unless returns_range.first_empty_comment?
+          add_offense(returns_range.end_comment, message: MSG_RETURNS_SHOULD_END_WITH_BLANK_COMMENT) unless returns_range.ends_with_empty_comment?
+
+          add_offense(attrs_range.start_comment, message: MSG_ATTRIBUTES_IS_MISSING_FIRST_BLANK_COMMENT) unless attrs_range.first_empty_comment?
+          ends_with_empty_comment_ = attrs_range.ends_with_empty_comment?
+          add_offense(attrs_range.end_comment, message: MSG_ATTRIBUTES_SHOULD_END_WITH_BLANK_COMMENT) unless ends_with_empty_comment_
+          # rubocop:enable Layout/LineLength
+        end
+
+        def check_body(range)
+          # puts "check_body=#{range.type} for #{@method_name}"
+          # puts range.start_comment.text
+          body = range.range_body
+          found = false
+          body.each_with_index do |line, _i|
+            # puts "check_body loop text=#{line.text}"
+            next if range.empty_comm?(line)
+
+            found = true
+            text = line.text.to_s
+            if range.returns?
+              # puts "check_body ret DOC_RET_REGEXP) text=#{DOC_RET_REGEXP.match(text)}"
+              # puts "check_body (DOC_SUB_PARM_REGEXP) text=#{DOC_SUB_PARM_REGEXP.match(text)}"
+              unless DOC_RET_REGEXP.match(text) || DOC_SUB_PARM_REGEXP.match(text)
+                add_offense(line, message: format(MSG_ILLEGAL_RANGE_RET_BODY_FORMAT, range.type)) unless text.start_with?('# **')
+                add_offense(line, message: format(MSG_ILLEGAL_RANGE_BODY_FORMAT_SUB, range.type)) if text.start_with?('# **')
+              end
+            else
+              # puts "check_body DOC_PARM_REGEXP) text=#{DOC_PARM_REGEXP.match(text)}"
+              # puts "check_body (DOC_SUB_PARM_REGEXP) text=#{DOC_SUB_PARM_REGEXP.match(text)}"
+              unless DOC_PARM_REGEXP.match(text) || DOC_SUB_PARM_REGEXP.match(text)
+                add_offense(line, message: format(MSG_ILLEGAL_RANGE_BODY_FORMAT, range.type)) unless text.start_with?('# **')
+                add_offense(line, message: format(MSG_ILLEGAL_RANGE_BODY_FORMAT_SUB, range.type)) if text.start_with?('# **')
+              end
+            end
+          end
+          # puts "check_body found=#{found}"
+          # puts "check_body adding_offense=#{found}" unless found
+          add_offense(range.start_comment, message: format(MSG_RANGE_BODY_EMPTY, range.type)) unless found
+        end
+
+        def check_parms_and_args(args, parameters_range)
+          # pns = parm_names(range_lines(preceding_lines, parameters_range))
+          pns = parameters_range.parm_names
+
+          # rubocop:disable Layout/LineLength
+          add_offense(pns[args.size][0], message: format(MSG_PARAMETERS_ARG_SIZE_MISMATCH, pns.size, args.size)) if pns.size > args.size
+          add_offense(args[pns.size], message: format(MSG_PARAMETERS_ARG_SIZE_MISMATCH, pns.size, args.size)) if args.size > pns.size
+          # rubocop:enable Layout/LineLength
+
+          match_parms_to_args(args, pns)
+        end
+
+        def match_parms_to_args(args, pns)
+          pns.each_with_index do |param_pair, i|
+            break if args[i].nil?
+
+            arg_name = get_arg_name(args[i])
+            param_line = param_pair[0]
+            param_name = param_pair[1]
+            # puts "Comparing arg name #{arg_name} with parm name #{param_name} ans=#{param_name == arg_name}"
+            next if param_name == arg_name
+
+            add_offense(
+              param_line,
+              message: format(MSG_PARAMETERS_ARG_NAME_MISMATCH, param_name, arg_name)
+            )
+          end
+        end
+
+        def get_arg_name(arg)
+          name = arg.node_parts[0].to_s
+          # handle unused arguments, which begin with _
+          return name[1...name.size] if name[0] == '_'
+
+          name
+        end
+      end
+
+      # method doc range checks parts of the comment for correctness
+      #
+      class MethodDocRange
+        attr_accessor(:end, :start, :type)
+
+        DOC_PARM_REGEXP = %r{^# \* <tt>:(\w+)</tt>}.freeze
+        PARM_START = '# * <tt>:'
+        PARM_END = '</tt>'
+
+        def initialize(comments, type)
+          @comments = comments
+          @type = type
+        end
+
+        def before?(method_doc_range)
+          return true if missing? || method_doc_range.missing?
+
+          @start < method_doc_range.start
+        end
+
+        def empty_comm?(comment)
+          txt = comment.text
+          txt.size <= 2
+        end
+
+        def end_comment
+          @comments[@end]
+        end
+
+        def ends_with_empty_comment?
+          missing? || empty_comm?(end_comment)
+        end
+
+        def first_comment?
+          @start == 0
+        end
+
+        def first_empty_comment?
+          missing? || empty_comm?(@comments[@start + 1])
+        end
+
+        def first_comment_equal?(text)
+          !missing? && start_comment.text == text
+        end
+
+        def missing?
+          @start.nil?
+        end
+
+        def parm_names
+          names = []
+          range_body.each do |parm_line|
+            # puts "parm_line.text=#{parm_line}"
+            # puts "match=#{DOC_PARM_REGEXP.match(parm_line.text).to_s}"
+            DOC_PARM_REGEXP.match(parm_line.text) do |m|
+              parm_name = m.to_s[PARM_START.size...m.to_s.index(PARM_END)]
+              names.push([parm_line, parm_name])
+              # puts "parm_name=#{parm_name}"
+            end
+          end
+          # puts "names=#{names}"
+          names
+        end
+
+        def range_body
+          @comments[@start + (first_empty_comment? ? 2 : 1)...@end + (ends_with_empty_comment? ? 0 : 1)]
+        end
+
+        def returns?
+          @type == 'Return'
+        end
+
+        def start_comment
+          @comments[@start]
+        end
+
+        def starts_with_empty_comment?
+          empty_comm?(@comments[@start])
+        end
+
+        def to_s
+          [missing? ? nil : start_comment, @start, @end]
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/publicdoc2/inject.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# The original code is from https://github.com/rubocop-hq/rubocop-rspec/blob/master/lib/rubocop/rspec/inject.rb
+# See https://github.com/rubocop-hq/rubocop-rspec/blob/master/MIT-LICENSE.md
+module RuboCop
+  module Publicdoc2
+    # Because RuboCop doesn't yet support plugins, we have to monkey patch in a
+    # bit of our configuration.
+    module Inject
+      def self.defaults!
+        path = CONFIG_DEFAULT.to_s
+        hash = ConfigLoader.send(:load_yaml_configuration, path)
+        config = Config.new(hash, path).tap(&:make_excludes_absolute)
+        puts "configuration from #{path}" if ConfigLoader.debug?
+        config = ConfigLoader.merge_with_default(config, path)
+        ConfigLoader.instance_variable_set(:@default_configuration, config)
+      end
+    end
+  end
+end

data/lib/rubocop/publicdoc2/version.rb

@@ -0,0 +1,5 @@
+module RuboCop
+  module Publicdoc2
+    VERSION = '0.1.2'
+  end
+end

data/lib/rubocop/publicdoc2.rb

@@ -0,0 +1,14 @@
+require "rubocop/publicdoc2/version"
+
+module RuboCop
+  module Publicdoc2
+    class Error < StandardError; end
+    # Your code goes here...
+    PROJECT_ROOT   = Pathname.new(__dir__).parent.parent.expand_path.freeze
+    CONFIG_DEFAULT = PROJECT_ROOT.join('config', 'default.yml').freeze
+    CONFIG         = YAML.safe_load(CONFIG_DEFAULT.read).freeze
+
+    private_constant(:CONFIG_DEFAULT, :PROJECT_ROOT)
+  end
+end
+

data/lib/rubocop-publicdoc2.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rubocop'
+
+require_relative 'rubocop/publicdoc2'
+require_relative 'rubocop/publicdoc2/version'
+require_relative 'rubocop/publicdoc2/inject'
+
+RuboCop::Publicdoc2::Inject.defaults!
+
+require_relative 'rubocop/cop/publicdoc2_cops'

data/rubocop-publicdoc2.gemspec

@@ -0,0 +1,37 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "rubocop/publicdoc2/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rubocop-publicdoc2"
+  spec.version       = RuboCop::Publicdoc2::VERSION
+  spec.authors       = ["Paul Kristoff"]
+  spec.email         = ["paul.kristoff@kristoffs.com"]
+
+  spec.summary       = %q{All public methods have the correct documentation}
+  # spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.homepage      = "https://github.com/pkristoff/rubocop-publicdoc2"
+  spec.license       = "MIT"
+
+  spec.metadata["allowed_push_host"] = 'https://rubygems.org'
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/pkristoff/rubocop-publicdoc2"
+  spec.metadata["changelog_uri"] = "https://github.com/pkristoff/rubocop-publicdoc2"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.17.2"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+
+  spec.add_runtime_dependency 'rubocop'
+end
+

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-publicdoc2
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Paul Kristoff
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-08-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.17.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.17.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- paul.kristoff@kristoffs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-gemset"
+- ".ruby-version"
+- ".travis.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- config/default.yml
+- lib/rubocop-publicdoc2.rb
+- lib/rubocop/cop/publicdoc2_cops.rb
+- lib/rubocop/cop/style/public_class_documentation.rb
+- lib/rubocop/cop/style/public_method_documentation.rb
+- lib/rubocop/publicdoc2.rb
+- lib/rubocop/publicdoc2/inject.rb
+- lib/rubocop/publicdoc2/version.rb
+- rubocop-publicdoc2.gemspec
+homepage: https://github.com/pkristoff/rubocop-publicdoc2
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/pkristoff/rubocop-publicdoc2
+  source_code_uri: https://github.com/pkristoff/rubocop-publicdoc2
+  changelog_uri: https://github.com/pkristoff/rubocop-publicdoc2
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key:
+specification_version: 4
+summary: All public methods have the correct documentation
+test_files: []