From 008e3a3751ffcb424b8d32cf884e69ac28ddd46b Mon Sep 17 00:00:00 2001
From: Zach Daniel <zach@zachdaniel.dev>
Date: Tue, 4 Oct 2022 01:30:47 -0400
Subject: [PATCH] docs: update docs for `Ash.Changeset.new`

---
 lib/ash/changeset/changeset.ex | 31 +++++++++----------------------
 1 file changed, 9 insertions(+), 22 deletions(-)

diff --git a/lib/ash/changeset/changeset.ex b/lib/ash/changeset/changeset.ex
index 06ac817b..0d7db0f0 100644
--- a/lib/ash/changeset/changeset.ex
+++ b/lib/ash/changeset/changeset.ex
@@ -143,33 +143,22 @@ defmodule Ash.Changeset do
   require Logger
 
   @doc """
-  Return a changeset over a resource or a record. `params` can be either attributes, relationship values or arguments.
+  Returns a new changeset over a resource. Prefer `for_action` or `for_create`, etc. over this function if possible.
 
-  If you are using external input, you almost certainly want to use `Ash.Changeset.for_<action_type>`. However, you can
-  use `Ash.Changeset.new/2` to start a changeset and make a few changes prior to calling `for_action`. For example:
+  Warning: You almost always want to use `for_action/4` (or `for_create`, etc...)
+
+  You can use this to start a changeset and make a few changes prior to calling `for_action`. For example:
 
   ```elixir
-  Ash.Changeset.new()
+  Resource
+  |> Ash.Changeset.new()
   |> Ash.Changeset.change_attribute(:name, "foobar")
   |> Ash.Changeset.for_action(...)
   ```
-
-  Anything that is modified prior to `for_action` is validated against the rules of the action, while *anything after it is not*.
-
-  This changeset does not consider an action, and so allows you to change things with minimal validation. Values are
-  validated when changed, and the existence of attributes and relationships are validated. If you want to essentially
-  "run an action", and get back a changeset with any errors that would be generated by that action (with the exception
-  of errors that can only be generated by the data layer), use `for_action/4`.
-
-  Additionally, this format only supports supplying attributes in the params. This is because we don't know what the
-  behavior should be for relationship changes, nor what arguments are available. You can manage them yourself with
-  the functions that allow managing arguments/relationships that are provided in this module, e.g `set_argument/3` and
-  `replace_relationship/3`
   """
-  @spec new(Ash.Resource.t() | Ash.Resource.record(), params :: map) :: t
-  def new(resource, params \\ %{})
+  @spec new(Ash.Resource.t() | Ash.Resource.record()) :: t
 
-  def new(%resource{} = record, params) do
+  def new(%resource{} = record) do
     tenant =
       record
       |> Map.get(:__metadata__, %{})
@@ -179,7 +168,6 @@ defmodule Ash.Changeset do
 
     if Ash.Resource.Info.resource?(resource) do
       %__MODULE__{resource: resource, data: record, action_type: :update}
-      |> change_attributes(params)
       |> set_context(context)
       |> set_tenant(tenant)
     else
@@ -194,14 +182,13 @@ defmodule Ash.Changeset do
     end
   end
 
-  def new(resource, params) do
+  def new(resource) do
     if Ash.Resource.Info.resource?(resource) do
       %__MODULE__{
         resource: resource,
         action_type: :create,
         data: struct(resource)
       }
-      |> change_attributes(params)
     else
       %__MODULE__{resource: resource, action_type: :create, data: struct(resource)}
       |> add_error(NoSuchResource.exception(resource: resource))