Clarify documentation by removing charged words

Using words such as 'just', 'simply' and 'easy' implies to the reader
that the tasks they are trying to accomplish are tasks that anyone can
do, which might then frustrate them if they find it difficult to
complete.

This commit rephrases some usage of these words to aid understanding in
the readers without making them feel belittled.

[ci skip]
This commit is contained in:
Kevin Jacoby 2019-12-12 19:43:51 +00:00
parent cad13033fc
commit b0743dda8c
6 changed files with 21 additions and 24 deletions

View File

@ -133,8 +133,7 @@ NOTE: While these column names are optional, they are in fact reserved by Active
Creating Active Record Models
-----------------------------
It is very easy to create Active Record models. All you have to do is to
subclass the `ApplicationRecord` class and you're good to go:
To create Active Record models, subclass the `ApplicationRecord` class and you're good to go:
```ruby
class Product < ApplicationRecord

View File

@ -354,7 +354,7 @@ The callback only runs when all the `:if` conditions and none of the `:unless` c
Callback Classes
----------------
Sometimes the callback methods that you'll write will be useful enough to be reused by other models. Active Record makes it possible to create classes that encapsulate the callback methods, so it becomes very easy to reuse them.
Sometimes the callback methods that you'll write will be useful enough to be reused by other models. Active Record makes it possible to create classes that encapsulate the callback methods, so they can be reused.
Here's an example where we create a class with an `after_destroy` callback for a `PictureFile` model:

View File

@ -5,8 +5,7 @@ Active Record Migrations
Migrations are a feature of Active Record that allows you to evolve your
database schema over time. Rather than write schema modifications in pure SQL,
migrations allow you to use an easy Ruby DSL to describe changes to your
tables.
migrations allow you to use a Ruby DSL to describe changes to your tables.
After reading this guide, you will know:
@ -22,7 +21,7 @@ Migration Overview
Migrations are a convenient way to
[alter your database schema over time](https://en.wikipedia.org/wiki/Schema_migration)
in a consistent and easy way. They use a Ruby DSL so that you don't have to
in a consistent way. They use a Ruby DSL so that you don't have to
write SQL by hand, allowing your schema and changes to be database independent.
You can think of each migration as being a new 'version' of the database. A
@ -497,7 +496,7 @@ NOTE: Active Record only supports single column foreign keys. `execute` and
`structure.sql` are required to use composite foreign keys. See
[Schema Dumping and You](#schema-dumping-and-you).
Removing a foreign key is easy as well:
Foreign keys can also be removed:
```ruby
# let Active Record figure out the column name
@ -789,7 +788,7 @@ $ rails db:migrate:redo STEP=3
```
Neither of these rails commands do anything you could not do with `db:migrate`. They
are simply more convenient, since you do not need to explicitly specify the
are there for convenience, since you do not need to explicitly specify the
version to migrate to.
### Setup the Database
@ -1036,9 +1035,9 @@ end
```
To add initial data after a database is created, Rails has a built-in
'seeds' feature that makes the process quick and easy. This is especially
'seeds' feature that speeds up the process. This is especially
useful when reloading the database frequently in development and test environments.
It's easy to get started with this feature: just fill up `db/seeds.rb` with some
To get started with this feature, fill up `db/seeds.rb` with some
Ruby code, and run `rails db:seed`:
```ruby

View File

@ -42,9 +42,8 @@ database. For example, it may be important to your application to ensure that
every user provides a valid email address and mailing address. Model-level
validations are the best way to ensure that only valid data is saved into your
database. They are database agnostic, cannot be bypassed by end users, and are
convenient to test and maintain. Rails makes them easy to use, provides
built-in helpers for common needs, and allows you to create your own validation
methods as well.
convenient to test and maintain. Rails provides built-in helpers for common
needs, and allows you to create your own validation methods as well.
There are several other ways to validate data before it is saved into your
database, including native database constraints, client-side validations and
@ -77,7 +76,7 @@ example using the `new` method, that object does not belong to the database
yet. Once you call `save` upon that object it will be saved into the
appropriate database table. Active Record uses the `new_record?` instance
method to determine whether an object is already in the database or not.
Consider the following simple Active Record class:
Consider the following Active Record class:
```ruby
class Person < ApplicationRecord
@ -123,7 +122,7 @@ database only if the object is valid:
The bang versions (e.g. `save!`) raise an exception if the record is invalid.
The non-bang versions don't: `save` and `update` return `false`, and
`create` just returns the object.
`create` returns the object.
### Skipping Validations
@ -204,7 +203,7 @@ end
# => ActiveRecord::RecordInvalid: Validation failed: Name can't be blank
```
`invalid?` is simply the inverse of `valid?`. It triggers your validations,
`invalid?` is the inverse of `valid?`. It triggers your validations,
returning true if any errors were found in the object, and false otherwise.
### `errors[]`
@ -307,7 +306,7 @@ end
This validation is very specific to web applications and this
'acceptance' does not need to be recorded anywhere in your database. If you
don't have a field for it, the helper will just create a virtual attribute. If
don't have a field for it, the helper will create a virtual attribute. If
the field does exist in your database, the `accept` option must be set to
or include `true` or else the validation will not run.
@ -1198,7 +1197,7 @@ validator type.
### `errors[:base]`
You can add error messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since `errors[:base]` is an array, you can simply add a string to it and it will be used as an error message.
You can add error messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since `errors[:base]` is an array, you can add a string to it and it will be used as an error message.
```ruby
class Person < ApplicationRecord
@ -1259,7 +1258,7 @@ validations fail.
Because every application handles this kind of thing differently, Rails does
not include any view helpers to help you generate these messages directly.
However, due to the rich number of methods Rails gives you to interact with
validations in general, it's fairly easy to build your own. In addition, when
validations in general, you can build your own. In addition, when
generating a scaffold, Rails will put some ERB into the `_form.html.erb` that
it generates that displays the full list of errors on that model.

View File

@ -406,7 +406,7 @@ NOTE: Using `t.bigint :supplier_id` makes the foreign key naming obvious and exp
### Choosing Between `has_many :through` and `has_and_belongs_to_many`
Rails offers two different ways to declare a many-to-many relationship between models. The simpler way is to use `has_and_belongs_to_many`, which allows you to make the association directly:
Rails offers two different ways to declare a many-to-many relationship between models. The first way is to use `has_and_belongs_to_many`, which allows you to make the association directly:
```ruby
class Assembly < ApplicationRecord
@ -2459,7 +2459,7 @@ Let's say we have Car, Motorcycle, and Bicycle models. We will want to share
the `color` and `price` fields and some methods for all of them, but having some
specific behavior for each, and separated controllers too.
Rails makes this quite easy. First, let's generate the base Vehicle model:
First, let's generate the base Vehicle model:
```bash
$ rails generate model vehicle type:string color:string price:decimal{10.2}
@ -2503,7 +2503,7 @@ will generate the following SQL:
INSERT INTO "vehicles" ("type", "color", "price") VALUES ('Car', 'Red', 10000)
```
Querying car records will just search for vehicles that are cars:
Querying car records will search only for vehicles that are cars:
```ruby
Car.all

View File

@ -48,9 +48,9 @@ Having a way to reproduce your issue will be very helpful for others to help con
These templates include the boilerplate code to set up a test case against either a released version of Rails (`*_gem.rb`) or edge Rails (`*_master.rb`).
Simply copy the content of the appropriate template into a `.rb` file and make the necessary changes to demonstrate the issue. You can execute it by running `ruby the_file.rb` in your terminal. If all goes well, you should see your test case failing.
Copy the content of the appropriate template into a `.rb` file and make the necessary changes to demonstrate the issue. You can execute it by running `ruby the_file.rb` in your terminal. If all goes well, you should see your test case failing.
You can then share your executable test case as a [gist](https://gist.github.com), or simply paste the content into the issue description.
You can then share your executable test case as a [gist](https://gist.github.com), or paste the content into the issue description.
### Special Treatment for Security Issues