Fix yard doc generation (#1006)

* Update guide.rb to check for `@guide` tag

* Add custom guide tag to .yardopts

* Update lib/friendly_id.rb docs

* Fix guide processing for indented comments

* Update lib/friendly_id/base.rb docs

* Update lib/friendly_id/finders.rb docs

* Update lib/friendly_id/slugged.rb docs

* Update lib/friendly_id/history.rb docs

* Update lib/friendly_id/scoped.rb docs

* Update lib/friendly_id/simple_i18n.rb docs

* Update lib/friendly_id/reserved.rb docs

.yardopts

@@ -1,5 +1,7 @@
 -e guide.rb
 --files=Changelog.md,Guide.md
+--tag guide
+--hide-tag guide
 --private
 --protected
 --exclude lib/friendly_id/migration

guide.rb

@@ -4,8 +4,15 @@
 
 def comments_from path
   path = File.expand_path("../lib/friendly_id/#{path}", __FILE__)
-  match = File.read(path).match(/\n=begin(.*)\n=end/m)[1].to_s
-  match.split("\n").reject { |x| x =~ /^@/ }.join("\n").strip
+  matches = File.read(path).match(/\n\s*# @guide begin\n(.*)\s*# @guide end/m)
+
+  return if matches.nil?
+
+  match = matches[1].to_s
+  match.split("\n")
+    .map { |x| x.sub(/^\s*#\s?/, "") } # Strip off the comment, leading whitespace, and the space after the comment
+    .reject { |x| x =~ /^@/ }         # Ignore yarddoc tags for the guide
+    .join("\n").strip
 end
 
 File.open(File.expand_path("../Guide.md", __FILE__), "w:utf-8") do |guide|

lib/friendly_id.rb

@@ -4,8 +4,9 @@
 require "friendly_id/configuration"
 require "friendly_id/finder_methods"
 
+# @guide begin
 #
-## About FriendlyId
+# ## About FriendlyId
 #
 # FriendlyId is an add-on to Ruby's Active Record that allows you to replace ids
 # in your URLs with strings:
@@ -19,17 +20,17 @@
 # It requires few changes to your application code and offers flexibility,
 # performance and a well-documented codebase.
 #
-### Core Concepts
+# ### Core Concepts
 #
-#### Slugs
+# #### Slugs
 #
 # The concept of *slugs* is at the heart of FriendlyId.
 #
 # A slug is the part of a URL which identifies a page using human-readable
 # keywords, rather than an opaque identifier such as a numeric id. This can make
 # your application more friendly both for users and search engines.
 #
-#### Finders: Slugs Act Like Numeric IDs
+# #### Finders: Slugs Act Like Numeric IDs
 #
 # To the extent possible, FriendlyId lets you treat text-based identifiers like
 # normal IDs. This means that you can perform finds with slugs just like you do
@@ -38,6 +39,7 @@
 #     Person.find(82542335)
 #     Person.friendly.find("joe")
 #
+# @guide end
 module FriendlyId
   autoload :History, "friendly_id/history"
   autoload :Slug, "friendly_id/slug"

lib/friendly_id/base.rb

@@ -1,6 +1,7 @@
 module FriendlyId
+  # @guide begin
   #
-  ## Setting Up FriendlyId in Your Model
+  # ## Setting Up FriendlyId in Your Model
   #
   # To use FriendlyId in your ActiveRecord models, you must first either extend or
   # include the FriendlyId module (it makes no difference), then invoke the
@@ -21,7 +22,7 @@ module FriendlyId
   # all classes that participate in STI, both your parent classes and their
   # children.*
   #
-  ### The Default Setup: Simple Models
+  # ### The Default Setup: Simple Models
   #
   # The simplest way to use FriendlyId is with a model that has a uniquely indexed
   # column with no spaces or special characters, and that is seldom or never
@@ -53,6 +54,7 @@ module FriendlyId
   # in a URL can be repetitive and surprisingly tricky, so for this reason it's
   # often better and easier to use {FriendlyId::Slugged slugs}.
   #
+  # @guide end
   module Base
     # Configure FriendlyId's behavior in a model.
     #

lib/friendly_id/finders.rb

@@ -1,4 +1,6 @@
 module FriendlyId
+  # @guide begin
+  #
   # ## Performing Finds with FriendlyId
   #
   # FriendlyId offers enhanced finders which will search for your record by
@@ -12,7 +14,7 @@ module FriendlyId
   #     Restaurant.find(23)                     #=> still works
   #     Restaurant.find('plaza-diner')          #=> will not work
   #
-  ### Restoring FriendlyId 4.0-style finders
+  # ### Restoring FriendlyId 4.0-style finders
   #
   # Prior to version 5.0, FriendlyId overrode the default finder methods to perform
   # friendly finds all the time. This required modifying parts of Rails that did
@@ -34,7 +36,7 @@ module FriendlyId
   #     Restaurant.find('plaza-diner')          #=> now also works
   #     Restaurant.active.find('plaza-diner')   #=> now also works
   #
-  ### Updating your application to use FriendlyId's finders
+  # ### Updating your application to use FriendlyId's finders
   #
   # Unless you've chosen to use the `:finders` addon, be sure to modify the finders
   # in your controllers to use the `friendly` scope. For example:
@@ -49,7 +51,7 @@ module FriendlyId
   #       @restaurant = Restaurant.friendly.find(params[:id])
   #     end
   #
-  #### Active Admin
+  # #### Active Admin
   #
   # Unless you use the `:finders` addon, you should modify your admin controllers
   # for models that use FriendlyId with something similar to the following:
@@ -60,6 +62,7 @@ module FriendlyId
   #       end
   #     end
   #
+  # @guide end
   module Finders
     module ClassMethods
       if (ActiveRecord::VERSION::MAJOR == 4) && (ActiveRecord::VERSION::MINOR == 0)

lib/friendly_id/history.rb

@@ -1,14 +1,15 @@
 module FriendlyId
+  # @guide begin
   #
-  ## History: Avoiding 404's When Slugs Change
+  # ## History: Avoiding 404's When Slugs Change
   #
   # FriendlyId's {FriendlyId::History History} module adds the ability to store a
   # log of a model's slugs, so that when its friendly id changes, it's still
   # possible to perform finds by the old id.
   #
   # The primary use case for this is avoiding broken URLs.
   #
-  ### Setup
+  # ### Setup
   #
   # In order to use this module, you must add a table to your database schema to
   # store the slug records. FriendlyId provides a generator for this purpose:
@@ -19,13 +20,13 @@ module FriendlyId
   # This will add a table named `friendly_id_slugs`, used by the {FriendlyId::Slug}
   # model.
   #
-  ### Considerations
+  # ### Considerations
   #
   # Because recording slug history requires creating additional database records,
   # this module has an impact on the performance of the associated model's `create`
   # method.
   #
-  ### Example
+  # ### Example
   #
   #     class Post < ActiveRecord::Base
   #       extend FriendlyId
@@ -49,6 +50,8 @@ module FriendlyId
   #         end
   #       end
   #     end
+  #
+  # @guide end
   module History
     module Configuration
       def dependent_value

lib/friendly_id/reserved.rb

@@ -1,6 +1,7 @@
 module FriendlyId
+  # @guide begin
   #
-  ## Reserved Words
+  # ## Reserved Words
   #
   # The {FriendlyId::Reserved Reserved} module adds the ability to exclude a list of
   # words from use as FriendlyId slugs.
@@ -26,6 +27,7 @@ module FriendlyId
   #       end
   #     end
   #
+  # @guide end
   module Reserved
     # When included, this module adds configuration options to the model class's
     # friendly_id_config.

lib/friendly_id/scoped.rb

@@ -1,8 +1,9 @@
 require "friendly_id/slugged"
 
 module FriendlyId
+  # @guide begin
   #
-  ## Unique Slugs by Scope
+  # ## Unique Slugs by Scope
   #
   # The {FriendlyId::Scoped} module allows FriendlyId to generate unique slugs
   # within a scope.
@@ -53,7 +54,7 @@ module FriendlyId
   #
   # All supplied values will be used to determine scope.
   #
-  ### Finding Records by Friendly ID
+  # ### Finding Records by Friendly ID
   #
   # If you are using scopes your friendly ids may not be unique, so a simple find
   # like:
@@ -70,13 +71,13 @@ module FriendlyId
   #     Restaurant.where(:city_id => @city.id).friendly.find("joes-diner")
   #
   #
-  ### Finding All Records That Match a Scoped ID
+  # ### Finding All Records That Match a Scoped ID
   #
   # Query the slug column directly:
   #
   #     Restaurant.where(:slug => "joes-diner")
   #
-  ### Routes for Scoped Models
+  # ### Routes for Scoped Models
   #
   # Recall that FriendlyId is a database-centric library, and does not set up any
   # routes for scoped models. You must do this yourself in your application. Here's
@@ -98,6 +99,7 @@ module FriendlyId
   #     http://example.org/cities/seattle/restaurants/joes-diner
   #     http://example.org/cities/chicago/restaurants/joes-diner
   #
+  # @guide end
   module Scoped
     # FriendlyId::Config.use will invoke this method when present, to allow
     # loading dependent modules prior to overriding them when necessary.

lib/friendly_id/simple_i18n.rb

@@ -1,8 +1,9 @@
 require "i18n"
 
 module FriendlyId
+  # @guide begin
   #
-  ## Translating Slugs Using Simple I18n
+  # ## Translating Slugs Using Simple I18n
   #
   # The {FriendlyId::SimpleI18n SimpleI18n} module adds very basic i18n support to
   # FriendlyId.
@@ -17,7 +18,7 @@ module FriendlyId
   # If you need to support two or more locales, you may wish to use the
   # friendly_id_globalize gem instead.
   #
-  ### Example migration
+  # ### Example migration
   #
   #     def self.up
   #       create_table :posts do |t|
@@ -32,7 +33,7 @@ module FriendlyId
   #       add_index :posts, :slug_pt_br
   #     end
   #
-  ### Finds
+  # ### Finds
   #
   # Finds will take into consideration the current locale:
   #
@@ -50,11 +51,11 @@ module FriendlyId
   #       Post.friendly.find("la-guerra-de-las-galaxias")
   #     end
   #
-  ### Creating Records
+  # ### Creating Records
   #
   # When new records are created, the slug is generated for the current locale only.
   #
-  ### Translating Slugs
+  # ### Translating Slugs
   #
   # To translate an existing record's friendly_id, use
   # {FriendlyId::SimpleI18n::Model#set_friendly_id}. This will ensure that the slug
@@ -69,6 +70,8 @@ module FriendlyId
   #     I18n.with_locale(:es) do
   #       post.set_friendly_id("La guerra de las galaxias")
   #     end
+  #
+  # @guide end
   module SimpleI18n
     # FriendlyId::Config.use will invoke this method when present, to allow
     # loading dependent modules prior to overriding them when necessary.

lib/friendly_id/slugged.rb

@@ -2,8 +2,9 @@
 require "friendly_id/candidates"
 
 module FriendlyId
+  # @guide begin
   #
-  ## Slugged Models
+  # ## Slugged Models
   #
   # FriendlyId can use a separate column to store slugs for models which require
   # some text processing.
@@ -34,7 +35,7 @@ module FriendlyId
   # unique. You may also wish to constrain it to NOT NULL, but this depends on your
   # app's behavior and requirements.
   #
-  ### Example Setup
+  # ### Example Setup
   #
   #     # your model
   #     class Post < ActiveRecord::Base
@@ -60,9 +61,9 @@ module FriendlyId
   #       end
   #     end
   #
-  ### Working With Slugs
+  # ### Working With Slugs
   #
-  #### Formatting
+  # #### Formatting
   #
   # By default, FriendlyId uses Active Support's
   # [parameterize](http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize)
@@ -72,7 +73,7 @@ module FriendlyId
   #     movie = Movie.create! :title => "Der Preis fürs Überleben"
   #     movie.slug #=> "der-preis-furs-uberleben"
   #
-  #### Column or Method?
+  # #### Column or Method?
   #
   # FriendlyId always uses a method as the basis of the slug text - not a column. At
   # first glance, this may sound confusing, but remember that Active Record provides
@@ -95,7 +96,7 @@ module FriendlyId
   #
   # FriendlyId refers to this internally as the "base" method.
   #
-  #### Uniqueness
+  # #### Uniqueness
   #
   # When you try to insert a record that would generate a duplicate friendly id,
   # FriendlyId will append a UUID to the generated slug to ensure uniqueness:
@@ -109,7 +110,7 @@ module FriendlyId
   # Previous versions of FriendlyId appended a numeric sequence to make slugs
   # unique, but this was removed to simplify using FriendlyId in concurrent code.
   #
-  #### Candidates
+  # #### Candidates
   #
   # Since UUIDs are ugly, FriendlyId provides a "slug candidates" functionality to
   # let you specify alternate slugs to use in the event the one you want to use is
@@ -147,20 +148,20 @@ module FriendlyId
   # unique slug, then FriendlyId will append a UUID to the first candidate as a
   # last resort.
   #
-  #### Sequence Separator
+  # #### Sequence Separator
   #
   # By default, FriendlyId uses a dash to separate the slug from a sequence.
   #
   # You can change this with the {FriendlyId::Slugged::Configuration#sequence_separator
   # sequence_separator} configuration option.
   #
-  #### Providing Your Own Slug Processing Method
+  # #### Providing Your Own Slug Processing Method
   #
   # You can override {FriendlyId::Slugged#normalize_friendly_id} in your model for
   # total control over the slug format. It will be invoked for any generated slug,
   # whether for a single slug or for slug candidates.
   #
-  #### Deciding When to Generate New Slugs
+  # #### Deciding When to Generate New Slugs
   #
   # As of FriendlyId 5.0, slugs are only generated when the `slug` field is nil. If
   # you want a slug to be regenerated,set the slug field to nil:
@@ -198,7 +199,7 @@ module FriendlyId
   #       end
   #     end
   #
-  #### Locale-specific Transliterations
+  # #### Locale-specific Transliterations
   #
   # Active Support's `parameterize` uses
   # [transliterate](http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-transliterate),
@@ -219,7 +220,7 @@ module FriendlyId
   #
   # This functionality was in fact taken from earlier versions of FriendlyId.
   #
-  #### Gotchas: Common Problems
+  # #### Gotchas: Common Problems
   #
   # FriendlyId uses a before_validation callback to generate and set the slug. This
   # means that if you create two model instances before saving them, it's possible
@@ -233,6 +234,7 @@ module FriendlyId
   # creating more than one nested record for a model that uses FriendlyId. See [this
   # Github issue](https://github.com/norman/friendly_id/issues/185) for discussion.
   #
+  # @guide end
   module Slugged
     # Sets up behavior and configuration options for FriendlyId's slugging
     # feature.