Overhaul the documentation

In an attempt to emphasise the API that most closely resembles the
underlying RE2 library's, rework the documentation to surface how
methods in the gem relate to the C++ API and lead with the new
`full_match` and `partial_match` methods.

Thanks to @rowanmanning for
https://rowanmanning.com/posts/writing-a-friendly-readme/ which
heavily influenced the structure of the new README.

.yardopts

@@ -1,3 +1,4 @@
+--markup markdown
 --title "RE2: Ruby bindings to RE2"
 ext/**/*.cc
 lib/**/*.rb

ext/re2/extconf.rb

@@ -1,7 +1,9 @@
-# re2 (http://github.com/mudge/re2)
-# Ruby bindings to re2, an "efficient, principled regular expression library"
+# re2 (https://github.com/mudge/re2)
+# Ruby bindings to RE2, a "fast, safe, thread-friendly alternative to
+# backtracking regular expression engines like those used in PCRE, Perl, and
+# Python".
 #
-# Copyright (c) 2010-2012, Paul Mucur (http://mudge.name)
+# Copyright (c) 2010, Paul Mucur (https://mudge.name)
 # Released under the BSD Licence, please see LICENSE.txt
 
 require 'mkmf'

ext/re2/recipes.rb

@@ -1,3 +1,11 @@
+# re2 (https://github.com/mudge/re2)
+# Ruby bindings to RE2, a "fast, safe, thread-friendly alternative to
+# backtracking regular expression engines like those used in PCRE, Perl, and
+# Python".
+#
+# Copyright (c) 2010, Paul Mucur (https://mudge.name)
+# Released under the BSD Licence, please see LICENSE.txt
+
 PACKAGE_ROOT_DIR = File.expand_path('../..', __dir__)
 REQUIRED_MINI_PORTILE_VERSION = '~> 2.8.5' # keep this version in sync with the one in the gemspec
 

lib/re2.rb

@@ -1,8 +1,11 @@
-# re2 (http://github.com/mudge/re2)
-# Ruby bindings to re2, an "efficient, principled regular expression library"
+# re2 (https://github.com/mudge/re2)
+# Ruby bindings to RE2, a "fast, safe, thread-friendly alternative to
+# backtracking regular expression engines like those used in PCRE, Perl, and
+# Python".
 #
-# Copyright (c) 2010-2014, Paul Mucur (http://mudge.name)
+# Copyright (c) 2010, Paul Mucur (https://mudge.name)
 # Released under the BSD Licence, please see LICENSE.txt
+
 begin
   ::RUBY_VERSION =~ /(\d+\.\d+)/
   require_relative "#{Regexp.last_match(1)}/re2.so"

lib/re2/regexp.rb

@@ -1,9 +1,17 @@
+# re2 (https://github.com/mudge/re2)
+# Ruby bindings to RE2, a "fast, safe, thread-friendly alternative to
+# backtracking regular expression engines like those used in PCRE, Perl, and
+# Python".
+#
+# Copyright (c) 2010, Paul Mucur (https://mudge.name)
+# Released under the BSD Licence, please see LICENSE.txt
+
 module RE2
   class Regexp
-    # Match the pattern against any substring of the given +text+ and return
-    # either a boolean (if no submatches are required) or a {RE2::MatchData}
-    # instance with the specified number of submatches (defaults to the total
-    # number of capturing groups).
+    # Match the pattern against any substring of the given `text` and return a
+    # {RE2::MatchData} instance with the specified number of submatches
+    # (defaults to the total number of capturing groups) or a boolean (if no
+    # submatches are required).
     #
     # The number of submatches has a significant impact on performance: requesting
     # one submatch is much faster than requesting more than one and requesting
@@ -13,26 +21,26 @@ class Regexp
     # @param [Hash] options the options with which to perform the match
     # @option options [Integer] :submatches how many submatches to extract (0
     #   is fastest), defaults to the total number of capturing groups
-    # @return [RE2::MatchData] if extracting any submatches
+    # @return [RE2::MatchData, nil] if extracting any submatches
     # @return [Boolean] if not extracting any submatches
     # @raise [ArgumentError] if given a negative number of submatches
     # @raise [NoMemoryError] if there was not enough memory to allocate the
     #   matches
     # @raise [TypeError] if given non-numeric submatches or non-hash options
     # @example
     #   r = RE2::Regexp.new('w(o)(o)')
-    #   r.partial_match('woot')
-    #   #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
+    #   r.partial_match('woot')                #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
+    #   r.partial_match('nope')                #=> nil
     #   r.partial_match('woot', submatches: 1) #=> #<RE2::MatchData "woo" 1:"o">
     #   r.partial_match('woot', submatches: 0) #=> true
     def partial_match(text, options = {})
       match(text, Hash(options).merge(anchor: :unanchored))
     end
 
-    # Match the pattern against the given +text+ exactly and return either a
-    # boolean (if no submatches are required) or a {RE2::MatchData} instance
-    # with the specified number of submatches (defaults to the total number of
-    # capturing groups).
+    # Match the pattern against the given `text` exactly and return a
+    # {RE2::MatchData} instance with the specified number of submatches
+    # (defaults to the total number of capturing groups) or a boolean (if no
+    # submatches are required).
     #
     # The number of submatches has a significant impact on performance: requesting
     # one submatch is much faster than requesting more than one and requesting
@@ -42,25 +50,20 @@ def partial_match(text, options = {})
     # @param [Hash] options the options with which to perform the match
     # @option options [Integer] :submatches how many submatches to extract (0
     #   is fastest), defaults to the total number of capturing groups
-    # @return [RE2::MatchData] if extracting any submatches
+    # @return [RE2::MatchData, nil] if extracting any submatches
     # @return [Boolean] if not extracting any submatches
     # @raise [ArgumentError] if given a negative number of submatches
     # @raise [NoMemoryError] if there was not enough memory to allocate the
     #   matches
     # @raise [TypeError] if given non-numeric submatches or non-hash options
     # @example
     #   r = RE2::Regexp.new('w(o)(o)')
-    #   r.full_match('woo')
-    #   #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
+    #   r.full_match('woo')                #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
+    #   r.full_match('woot')               #=> nil
     #   r.full_match('woo', submatches: 1) #=> #<RE2::MatchData "woo" 1:"o">
     #   r.full_match('woo', submatches: 0) #=> true
-    #   r.full_match('woot') #=> nil
     def full_match(text, options = {})
       match(text, Hash(options).merge(anchor: :anchor_both))
     end
-
-    alias_method :=~, :match?
-    alias_method :===, :match?
-    alias_method :partial_match?, :match?
   end
 end

lib/re2/scanner.rb

@@ -1,3 +1,11 @@
+# re2 (https://github.com/mudge/re2)
+# Ruby bindings to RE2, a "fast, safe, thread-friendly alternative to
+# backtracking regular expression engines like those used in PCRE, Perl, and
+# Python".
+#
+# Copyright (c) 2010, Paul Mucur (https://mudge.name)
+# Released under the BSD Licence, please see LICENSE.txt
+
 module RE2
   class Scanner
     include Enumerable

lib/re2/string.rb

@@ -1,42 +1,31 @@
-# re2 (http://github.com/mudge/re2)
-# Ruby bindings to re2, an "efficient, principled regular expression library"
+# re2 (https://github.com/mudge/re2)
+# Ruby bindings to RE2, a "fast, safe, thread-friendly alternative to
+# backtracking regular expression engines like those used in PCRE, Perl, and
+# Python".
 #
-# Copyright (c) 2010-2014, Paul Mucur (http://mudge.name)
+# Copyright (c) 2010, Paul Mucur (https://mudge.name)
 # Released under the BSD Licence, please see LICENSE.txt
 
 require "re2"
 
 module RE2
   module String
-    # @deprecated Replaces the first occurrence +pattern+ with +rewrite+ and
-    # returns a new string.
-    #
-    # @see RE2.Replace
+    # @deprecated Use {RE2.Replace} instead.
     def re2_sub(*args)
       RE2.Replace(self, *args)
     end
 
-    # @deprecated Replaces every occurrence of +pattern+ with +rewrite+ and
-    # return a new string.
-    #
-    # @see RE2.GlobalReplace
+    # @deprecated Use {RE2.GlobalReplace} instead.
     def re2_gsub(*args)
       RE2.GlobalReplace(self, *args)
     end
 
-    # @deprecated Match the pattern and return either a boolean (if no
-    # submatches are required) or a {RE2::MatchData} instance.
-    #
-    # @see RE2::Regexp#match
+    # @deprecated Use {RE2::Regexp#match} instead.
     def re2_match(pattern, *args)
       RE2::Regexp.new(pattern).match(self, *args)
     end
 
-    # @deprecated Escapes all potentially meaningful regexp characters. The
-    # returned string, used as a regular expression, will exactly match the
-    # original string.
-    #
-    # @see RE2.quote
+    # @deprecated Use {RE2.QuoteMeta} instead.
     def re2_escape
       RE2.QuoteMeta(self)
     end

lib/re2/version.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# re2 (https://github.com/mudge/re2)
+# Ruby bindings to RE2, a "fast, safe, thread-friendly alternative to
+# backtracking regular expression engines like those used in PCRE, Perl, and
+# Python".
+#
+# Copyright (c) 2010, Paul Mucur (https://mudge.name)
+# Released under the BSD Licence, please see LICENSE.txt
+
 module RE2
   VERSION = "2.4.3"
 end