From a91e606d48dc3a11dccedad9e4b3ebae11577d0a Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:21:58 +0200
Subject: [PATCH] Document `FormulaAudit::Caveats`.

---
 Library/Homebrew/rubocops/caveats.rb | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Library/Homebrew/rubocops/caveats.rb b/Library/Homebrew/rubocops/caveats.rb
index 09233e48ea..f81c4fc26f 100644
--- a/Library/Homebrew/rubocops/caveats.rb
+++ b/Library/Homebrew/rubocops/caveats.rb
@@ -5,6 +5,24 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
+      # This cop makes sure that caveats don't recommend unsupported or unsafe operations.
+      #
+      # @example
+      #   # bad
+      #   def caveats
+      #     <<~EOS
+      #       Use `setuid` to allow running the exeutable by non-root users.
+      #     EOS
+      #   end
+      #
+      #   # good
+      #   def caveats
+      #     <<~EOS
+      #       Use `sudo` to run the executable.
+      #     EOS
+      #   end
+      #
+      # @api private
       class Caveats < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, _body_node)
           caveats_strings.each do |n|