Move documentation-related rules into its own group

spec/ameba/rule/documentation/documentation_admonition_spec.cr

@@ -0,0 +1,113 @@
+require "../../../spec_helper"
+
+module Ameba::Rule::Documentation
+  subject = DocumentationAdmonition.new
+
+  describe DocumentationAdmonition do
+    it "passes for comments with admonition mid-word/sentence" do
+      subject.admonitions.each do |admonition|
+        expect_no_issues subject, <<-CRYSTAL
+          # Mentioning #{admonition} mid-sentence
+          # x#{admonition}x
+          # x#{admonition}
+          # #{admonition}x
+          CRYSTAL
+      end
+    end
+
+    it "fails for comments with admonition" do
+      subject.admonitions.each do |admonition|
+        expect_issue subject, <<-CRYSTAL
+          # #{admonition}: Single-line comment
+          # ^{} error: Found a #{admonition} admonition in a comment
+          CRYSTAL
+
+        expect_issue subject, <<-CRYSTAL
+          # Text before ...
+          # #{admonition}(some context): Part of multi-line comment
+          # ^{} error: Found a #{admonition} admonition in a comment
+          # Text after ...
+          CRYSTAL
+
+        expect_issue subject, <<-CRYSTAL
+          # #{admonition}
+          # ^{} error: Found a #{admonition} admonition in a comment
+          if rand > 0.5
+          end
+          CRYSTAL
+      end
+    end
+
+    context "with date" do
+      it "passes for admonitions with future date" do
+        subject.admonitions.each do |admonition|
+          future_date = (Time.utc + 21.days).to_s(format: "%F")
+          expect_no_issues subject, <<-CRYSTAL
+            # #{admonition}(#{future_date}): sth in the future
+            CRYSTAL
+        end
+      end
+
+      it "fails for admonitions with past date" do
+        subject.admonitions.each do |admonition|
+          past_date = (Time.utc - 21.days).to_s(format: "%F")
+          expect_issue subject, <<-CRYSTAL
+            # #{admonition}(#{past_date}): sth in the past
+            # ^{} error: Found a #{admonition} admonition in a comment (21 days past)
+            CRYSTAL
+        end
+      end
+
+      it "fails for admonitions with yesterday's date" do
+        subject.admonitions.each do |admonition|
+          yesterday_date = (Time.utc - 1.day).to_s(format: "%F")
+          expect_issue subject, <<-CRYSTAL
+            # #{admonition}(#{yesterday_date}): sth in the past
+            # ^{} error: Found a #{admonition} admonition in a comment (1 day past)
+            CRYSTAL
+        end
+      end
+
+      it "fails for admonitions with today's date" do
+        subject.admonitions.each do |admonition|
+          today_date = Time.utc.to_s(format: "%F")
+          expect_issue subject, <<-CRYSTAL
+            # #{admonition}(#{today_date}): sth in the past
+            # ^{} error: Found a #{admonition} admonition in a comment (today is the day!)
+            CRYSTAL
+        end
+      end
+
+      it "fails for admonitions with invalid date" do
+        subject.admonitions.each do |admonition|
+          expect_issue subject, <<-CRYSTAL
+            # #{admonition}(0000-00-00): sth wrong
+            # ^{} error: #{admonition} admonition error: Invalid time: "0000-00-00"
+            CRYSTAL
+        end
+      end
+    end
+
+    context "properties" do
+      describe "#admonitions" do
+        it "lets setting custom admonitions" do
+          rule = DocumentationAdmonition.new
+          rule.admonitions = %w[FOO BAR]
+
+          rule.admonitions.each do |admonition|
+            expect_issue rule, <<-CRYSTAL
+              # #{admonition}
+              # ^{} error: Found a #{admonition} admonition in a comment
+              CRYSTAL
+          end
+
+          subject.admonitions.each do |admonition|
+            expect_no_issues rule, <<-CRYSTAL
+              # #{admonition}
+              CRYSTAL
+          end
+        end
+      end
+    end
+  end
+end

spec/ameba/rule/documentation/documentation_spec.cr

@@ -0,0 +1,151 @@
+require "../../../spec_helper"
+
+module Ameba::Rule::Documentation
+  subject = Documentation.new
+    .tap(&.ignore_classes = false)
+    .tap(&.ignore_modules = false)
+    .tap(&.ignore_enums = false)
+    .tap(&.ignore_defs = false)
+    .tap(&.ignore_macros = false)
+
+  describe Documentation do
+    it "passes for undocumented private types" do
+      expect_no_issues subject, <<-CRYSTAL
+        private class Foo
+          def foo
+          end
+        end
+
+        private module Bar
+          def bar
+          end
+        end
+
+        private enum Baz
+        end
+
+        private def bat
+        end
+
+        private macro bag
+        end
+      CRYSTAL
+    end
+
+    it "passes for documented public types" do
+      expect_no_issues subject, <<-CRYSTAL
+        # Foo
+        class Foo
+          # foo
+          def foo
+          end
+        end
+
+        # Bar
+        module Bar
+          # bar
+          def bar
+          end
+        end
+
+        # Baz
+        enum Baz
+        end
+
+        # bat
+        def bat
+        end
+
+        # bag
+        macro bag
+        end
+      CRYSTAL
+    end
+
+    it "fails if there is an undocumented public type" do
+      expect_issue subject, <<-CRYSTAL
+        class Foo
+      # ^^^^^^^^^ error: Missing documentation
+        end
+
+        module Bar
+      # ^^^^^^^^^^ error: Missing documentation
+        end
+
+        enum Baz
+      # ^^^^^^^^ error: Missing documentation
+        end
+
+        def bat
+      # ^^^^^^^ error: Missing documentation
+        end
+
+        macro bag
+      # ^^^^^^^^^ error: Missing documentation
+        end
+      CRYSTAL
+    end
+
+    context "properties" do
+      describe "#ignore_classes" do
+        it "lets the rule to ignore method definitions if true" do
+          rule = Documentation.new
+          rule.ignore_classes = true
+
+          expect_no_issues rule, <<-CRYSTAL
+            class Foo
+            end
+            CRYSTAL
+        end
+      end
+
+      describe "#ignore_modules" do
+        it "lets the rule to ignore method definitions if true" do
+          rule = Documentation.new
+          rule.ignore_modules = true
+
+          expect_no_issues rule, <<-CRYSTAL
+            module Bar
+            end
+            CRYSTAL
+        end
+      end
+
+      describe "#ignore_enums" do
+        it "lets the rule to ignore method definitions if true" do
+          rule = Documentation.new
+          rule.ignore_enums = true
+
+          expect_no_issues rule, <<-CRYSTAL
+            enum Baz
+            end
+            CRYSTAL
+        end
+      end
+
+      describe "#ignore_defs" do
+        it "lets the rule to ignore method definitions if true" do
+          rule = Documentation.new
+          rule.ignore_defs = true
+
+          expect_no_issues rule, <<-CRYSTAL
+            def bat
+            end
+            CRYSTAL
+        end
+      end
+
+      describe "#ignore_macros" do
+        it "lets the rule to ignore macros if true" do
+          rule = Documentation.new
+          rule.ignore_macros = true
+
+          expect_no_issues rule, <<-CRYSTAL
+            macro bag
+            end
+            CRYSTAL
+        end
+      end
+    end
+  end
+end