[DRAFT] Elixir Optional parameters

[Doerge]

This PR:

• Moves optional positional parameters to a Keywordlist.
• Documents optional parameters and their types, as best as possible.
• Improves docs formatting.
• Improves typespecs.
• Only includes the beginning of the AWS docs for a method, and links (as best as possible) to the online page instead.

https://github.com/aws-beam/aws-elixir/blob/master/lib/aws/generated/s3.ex#L8374
Latest (16/7/2024):
https://github.com/Doerge/aws-elixir/blob/140deecfb1387b14bf5da4c683b4086b44bf9629/lib/aws/generated/s3.ex#L7655

TODO:

• Also fix the POST requests? STS generated doesn't look right https://github.com/Doerge/aws-elixir/blob/dev/optional-parameters-wip/lib/aws/generated/sts.ex

[Doerge]

I'd still like to validate the optional parameters with Keyword.validate!, but because the optional params are popped off, and then the rest is passed down to the client, this is not possible. I.e. if an optional param is misspelled, it just get's sent to the client.

Possible solutions:
a. Group all client-related params under a keyword like client_opts.
b. Add a second optional positional parameter client_opts that is passed down to the client.

I think option a. is easier, and cleaner. Will draft that up.
Note: Tesla uses the adapter keyword.

[yordis]

Since the operations already take a client argument, couldn't you just put the client opts there?

client
|> put_opts() # do things before
|> get_bucket_website() # only about operations

[Doerge]

Ah, that's actually a really good idea! Completely bypasses the issue.
I'd probably add that as a little utility function:

defmodule AWS.Client do
  [...]
  def put_http_opts(%__MODULE__{} = client, opts) do
      {http_client, default_opts} = client.http_client
      final_opts = Keyword.merge(default_opts, opts)
    
      client
      |> AWS.Client.put_http_client({http_client, opts})
  end
end

my_client
|> AWS.Client.put_http_opts(foo: false)
|> get_bucket_website()

What do you think?

[yordis]

That works; it is similar to https://github.com/elixir-tesla/tesla/blob/d39d575af3edb87cc156b803317ebb7f7670b45f/lib/tesla.ex#L182 So some extent, you are chasing something similar to Tesla but one layer above

[Doerge]

I went ahead with this and now have optional parameter validation:
https://github.com/Doerge/aws-elixir/blob/140deecfb1387b14bf5da4c683b4086b44bf9629/lib/aws/generated/s3.ex#L11621

Basic tests here: https://github.com/Doerge/aws-elixir/blob/dev/optional-parameters-wip-2/test/aws/generated/s3_test.exs