Skip to content

Commit

Permalink
Fix yard doc generation (#1006)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
amiel authored Aug 24, 2023
1 parent cc648ab commit a72fac9
Show file tree
Hide file tree
Showing 10 changed files with 65 additions and 37 deletions.
2 changes: 2 additions & 0 deletions .yardopts
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
-e guide.rb
--files=Changelog.md,Guide.md
--tag guide
--hide-tag guide
--private
--protected
--exclude lib/friendly_id/migration
Expand Down
11 changes: 9 additions & 2 deletions guide.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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|
Expand Down
10 changes: 6 additions & 4 deletions lib/friendly_id.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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"
Expand Down
6 changes: 4 additions & 2 deletions lib/friendly_id/base.rb
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
#
Expand Down
9 changes: 6 additions & 3 deletions lib/friendly_id/finders.rb
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
module FriendlyId
# @guide begin
#
# ## Performing Finds with FriendlyId
#
# FriendlyId offers enhanced finders which will search for your record by
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -60,6 +62,7 @@ module FriendlyId
# end
# end
#
# @guide end
module Finders
module ClassMethods
if (ActiveRecord::VERSION::MAJOR == 4) && (ActiveRecord::VERSION::MINOR == 0)
Expand Down
11 changes: 7 additions & 4 deletions lib/friendly_id/history.rb
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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
Expand All @@ -49,6 +50,8 @@ module FriendlyId
# end
# end
# end
#
# @guide end
module History
module Configuration
def dependent_value
Expand Down
4 changes: 3 additions & 1 deletion lib/friendly_id/reserved.rb
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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.
Expand Down
10 changes: 6 additions & 4 deletions lib/friendly_id/scoped.rb
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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.
Expand Down
13 changes: 8 additions & 5 deletions lib/friendly_id/simple_i18n.rb
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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|
Expand All @@ -32,7 +33,7 @@ module FriendlyId
# add_index :posts, :slug_pt_br
# end
#
### Finds
# ### Finds
#
# Finds will take into consideration the current locale:
#
Expand All @@ -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
Expand All @@ -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.
Expand Down
26 changes: 14 additions & 12 deletions lib/friendly_id/slugged.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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),
Expand All @@ -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
Expand All @@ -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.
Expand Down

0 comments on commit a72fac9

Please sign in to comment.