Document and implement options to `serializable_hash`

[bf4]

Expected behavior vs actual behavior

The only things that we should ever explicitly pass to to_json and friends are the options that go to ActiveModel::Serialization and ActiveModel::Serializers::JSON

i.e. only, except, methods, include

The reason is that render json: resource, options essentially results in the Rails Renderer logic below.

resource = ActiveModel::Serializable_resource.new(resource, options)
resource.to_json(options) unless resource.is_a?(String)

This continues work from #1494

Related, #1572 fixes a case where we accidentally are using options passing into serializable_hash

Details

This is how AMS fits into rendering and why I'm thinking this way

render json: record, options
# |-> https://github.com/rails/rails/blob/v5.0.0.beta3/actionpack/lib/action_controller/metal/renderers.rb#L151-L152
  _render_with_renderer_json(record, options)
+  # |-> https://github.com/rails-api/active_model_serializers/blob/d30aa4c44fe004821be49d3427b56973f95c4984/lib/action_controller/serialization.rb#L46-L52
+    record = ActiveModel::Serializable_resource.new(record, options)
    # |-> https://github.com/rails/rails/blob/v5.0.0.beta3/actionpack/lib/action_controller/metal/renderers.rb#L159
      record.to_json(options) unless record.is_a?(String)
      # |-> https://github.com/rails/rails/blob/v5.0.0.beta3/activemodel/lib/active_model/serializers/json.rb#L88-L92
        record.as_json(options)
        # |-> https://github.com/rails/rails/blob/v5.0.0.beta3/activemodel/lib/active_model/serialization.rb#L124-L137
          record.serializable_hash(options)

where serializalbe_hash is where the options only, except, methods, include are defined, and as_json defines the option root and uses include_root_in_json.

[groyoh]

What is the goal of the methods options?

[bf4]

Goal? It's been in Rails json serialization since 2011. It's just calls that method.

[bf4]

Closed by #1678