docs: options representation in new APIs

[MarkoMin]

Decided to make this "official" after the discussion in #10472 , seems like this discussion arrives repeatedly from time to time and having this in the repo will (I hope) result in more consistent code eventually.

Content is taken from: https://erlangforums.com/t/handling-options-in-erlang-otp-apis/1133 with some slight modifications (e.g. to use lists if the module already uses lists).

[github-actions]

CT Test Results

  1 files   11 suites   2m 56s ⏱️
 95 tests  91 ✅ 4 💤 0 ❌
111 runs  107 ✅ 4 💤 0 ❌

Results for commit 4fee108.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

• Complete CT logs (Download Logs)
• HTML Documentation (Download HTML Docs)
• No Windows Installer found

// Erlang/OTP Github Action Bot

[Maria-12648430]

It may be good to mention that, if lists are used for the reason that existing functions in the same module use them, in the new function they should follow the semantics of the existing ones. That is, in some functions in some modules the first of repeated options "wins", in others it is the last, in some they "pile up". Some functions ignore unknown options, some complain... Etc.

[michalmuskala]

TBH I would hold off on this.

I think with the introduction of native records a lot of the tradeoffs around this will change massively. In particular native records will be almost as efficient as current records (more efficient than maps and vastly more efficient than proplists), won't have any issues that require header files or recompilation, can provide clear defaults, and can be better supported by various tools such as IDEs for autocomplete or type-checkers such as eqWAlizer or dialyzer.

[MarkoMin]

I think with the introduction of native records a lot of the tradeoffs around this will change massively.

oh, completely missed that. Yeah, when implemented they should be mentioned here, but that only makes this MR more important because contributors will be even more confused than today because now we have lists vs maps vs native records.

2 options here:

1. Merge this in the current state, modify when native records get implemented (and OTP team express new recommendations)
2. Postpone this, change the milestone to OTP29 and merge this after native records.