https://git.ruby-lang.org/ruby.git/commit/?id=112254d185

From 112254d18500b2d4cef19bc36290263c0de38e79 Mon Sep 17 00:00:00 2001
From: Benoit Daloze <eregontp@g...>
Date: Fri, 2 Oct 2020 12:02:54 +0200
Subject: Improve docs of the Warning module


diff --git a/error.c b/error.c
index fff9b4a..1eccedf 100644
--- a/error.c
+++ b/error.c
@@ -239,6 +239,8 @@ rb_warning_s_aset(VALUE mod, VALUE category, VALUE flag) https://github.com/ruby/ruby/blob/trunk/error.c#L239
  * Writes warning message +msg+ to $stderr. This method is called by
  * Ruby for all emitted warnings. A +category+ may be included with
  * the warning, but is ignored by default.
+ *
+ * See the documentation of the Warning module for how to customize this.
  */
 
 static VALUE
@@ -265,11 +267,30 @@ rb_warning_s_warn(int argc, VALUE *argv, VALUE mod) https://github.com/ruby/ruby/blob/trunk/error.c#L267
  *  Warning.warn is called for all warnings issued by Ruby.
  *  By default, warnings are printed to $stderr.
  *
- *  By overriding Warning.warn, you can change how warnings are
- *  handled by Ruby, either filtering some warnings, and/or outputting
- *  warnings somewhere other than $stderr.  When Warning.warn is
- *  overridden, super can be called to get the default behavior of
- *  printing the warning to $stderr.
+ *  Changing the behavior of Warning.warn is useful to customize how warnings are
+ *  handled by Ruby, for instance by filtering some warnings, and/or outputting
+ *  warnings somewhere other than $stderr.
+ *
+ *  If you want to change the behavior of Warning.warn you should use
+ *  +Warning.extend(MyNewModuleWithWarnMethod)+ and you can use `super`
+ *  to get the default behavior of printing the warning to $stderr.
+ *
+ *  Example:
+ *    module MyWarningFilter
+ *      def warn(message)
+ *        if /some warning I want to ignore/.matches?(message)
+ *          # ignore
+ *        else
+ *          super(message)
+ *        end
+ *      end
+ *    end
+ *    Warning.extend MyWarningFilter
+ *
+ *  You should never redefine Warning#warn (the instance method), as that will
+ *  then no longer provide a way to use the default behavior.
+ *
+ *  The +warning+ gem provides convenient ways to customize Warning.warn.
  */
 
 static VALUE
-- 
cgit v0.10.2


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/