More API documentation.

And remove the documented stuff from the `example-formula.rb`.

Closes Homebrew/homebrew#43241.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>

1 files changed, 7 insertions, 0 deletions

diff --git a/Library/Homebrew/utils/inreplace.rb b/Library/Homebrew/utils/inreplace.rb
index 8ed32bc5b..ee47da457 100644
--- a/Library/Homebrew/utils/inreplace.rb
+++ b/Library/Homebrew/utils/inreplace.rb
@@ -8,6 +8,13 @@ module Utils
   end
 
   module Inreplace
+    # Sometimes we have to change a bit before we install. Mostly we
+    # prefer a patch but if you need the `prefix` of this formula in the
+    # patch you have to resort to `inreplace`, because in the patch
+    # you don't have access to any var defined by the formula. Only
+    # HOMEBREW_PREFIX is available in the embedded patch.
+    # inreplace supports regular expressions.
+    # <pre>inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"</pre>
     def inreplace(paths, before = nil, after = nil)
       errors = {}