Update documentation to note object type returned by `versions`

It was unclear in the documentation that overriding the `versions` method would
result in changed behavior not just when retrieving versions but also in
creating them. This commit adds some documentation so the user is aware of this
behavior.
This commit is contained in:
Devon Estes 2016-05-09 15:08:28 -07:00
parent d9beeb012b
commit d0a019b10b
1 changed files with 24 additions and 1 deletions

View File

@ -156,7 +156,7 @@ class Widget < ActiveRecord::Base
end
# Returns this widget's versions. You can customise the name of the
# association.
# association, but overriding this method is not supported.
widget.versions
# Return the version this widget was reified from, or nil if it is live.
@ -999,6 +999,29 @@ end
However, there is a known issue when reifying [associations](#associations),
see https://github.com/airblade/paper_trail/issues/594
## Overriding the `versions` method
Overriding the `versions` method is officially not supported, but you can
change the name of that association. Because `versions` returns an
`ActiveRecord::Relation` object, changes to that method will result in changes
both to how records are retrieved _and_ how records are created.
If you absolutely must override this method to maintain your object's API,
you can do so safely by changing the name of the association.
```ruby
module News
class Post < ActiveRecord::Base
has_paper_trail class_name: 'Version', versions: :base_versions
def versions
types = ['Post', 'News::Post']
@versions ||= Version.where(item_id: id, item_type: types)
end
end
end
```
## Custom Version Classes
You can specify custom version subclasses with the `:class_name` option: