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,6 +1,14 @@
+# 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
+    # 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).
@@ -13,23 +21,23 @@ 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
+    # 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).
@@ -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,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-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"

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