NEP: Edit nep-0042 for more clarity (#17370)

* DOC: Edit NEP-42 for clarity

* DOC: Further edits of NEP 42

* DOC: Edit NEP-42 for clarity

* DOC: Further edits of NEP 42

* WIP: Work out structure a bit and make intro longer

* DOC: Round 3 of NEP 42 edits

* Start with a new motivation/overview to be forced upon the rest

* restructure along "top-level" categories and rename adjust_descriptors

* Small fixups

* Small clarity/correctness edits

* Use `PyArrayMethod` instead of UFuncImpl

I am starting to feel that calling this "array method" (even if
it is in no way numpy array specific) is probably the best name.
It is not ufunc specific, because ufuncs are dispatching + array method.
Calling it ufuncimpl makes sense, but since the UFunc name which would
also work perfectly is already taken, maybe a whole new name is better.

* DOC: Fold in @seberg revisions

* Fix typo

* Make first example/overview inherit dtype instead of metaclass

it could say `metaclass=DTypeMeta`, but its implicit.

* DOC: Add "checklist" to NEP 42

Also anchor NEP 40 figure for reference in NEP 42.

* Delete duplicated dtype-discovery section

The section must have been duplicated in an merge conflict :/,
I scanned through, and I think the version that was in the right place
got most edits, although not 100% sure.

* DOC: Reorganize scope, standardize heds

* DOC: Retitle, revisions up to Casting

Also anchor for parametric type discussion in NEP 40

* Some smaller changes/additions

* DOC: Reorganize for better flow

Also adds a NEP anchor at top.

* DOC: Glossary, shuffle "Additional information" bullets

* DOC: Small updates for sense and case

* Fixup merge (some changes were not saved when finishing merge)

* Answer bjnath's questions and motivate user impact

It seems most answers bjnath already included himself, this adds
a few tweaks.
Added a note that tusers will basically have to implement the
DType class as outlined is basically what the user will have to
implement, so spell that out both at the top and in the C-API to
clarify that.

* NEP 41: Add subsection on dtype organization with parameters

This might go a bit far, but I think the image goes very far in
giving people the right idea of how to think of dtypes and
DType instances.

The question is if we want to even show the "alternative"...

* Add bjnath as author

* Add new header also to NEP 41

* DOC: Minor: delete horiz rules, tweak 2 headings

* Rephrase NEP 41 bullt points in terms of NEP 42

Also changes those for NEP 43, to represent what is done, rather
than what is solved (and thus fit better to the way its written
for the NEP 42 part)

* Try to rewerd paragraphs around setitem/getitem a bit

some of these were very confusing, hopefully they are a bit better
now.

* Make a pass over the array-coercion part

* Make careful pass up until array-coercion

* Pass over the second half of the NEP 42 draft.

* Use "given_descrs" which seems clearer and fix casting

I always thought returning the casting safety is an awesome idea, but
right now I am actually not so sure it helps much with anything.
Its usually simpler, I guess. But if the user requested safe casting
and we have an unsafe cast, for example for structured dtypes we
will end up doing a lot of work for no reason.

If we accept an error return without an error already set this is
solved. My original reason was that setting a generic error in the
resolve descriptor function would really be pretty annoying, so
that returning the casting safety seemed like a good way to
avoid worrying about most errors there.

The "cast-is-view" output is important though.

* Fix copy new intro note to NEP 40 (and fix it in NEP 41)

Co-authored-by: Ben Nathanson <github@bigriver.xyz>

0 files changed, 0 insertions, 0 deletions