Clarify next-gen auto_attribs inference rules

[asford]

The next-gen auto_attribs api documentation does not clearly describe
cases where (a) only a subset of attributes are annotated and (b)
field definitions are provided for a subset of fields. Update
docstring to reflect current, desirable, behavior.

Add tests to clarify .define behavior focused on fully-annotated
classes with partially-defined fields, which is commonly used to add
non-default behavior to a subset of a classes fields. For example:

@attr.define
class NewSchool:
    x: int
    y: list = attr.field()

    @y.validator
    def _validate_y(self, attribute, value):
        if value < 0:
            raise ValueError("y must be positive")

The previous docstring could be read to imply that:

• The new-school API will not infer auto_attribs if there are any
  unannotated attributes.
• The new-school API will not infer auto_attribs if any attr.ib are
  defined, even if those attr.ibs are type annotated.

Pull Request Check List

This is just a friendly reminder about the most common mistakes. Please make sure that you tick all boxes. But please read our contribution guide at least once, it will save you unnecessary review cycles!

If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing left to do. If your pull request is a documentation fix or a trivial typo, feel free to delete the whole thing.

• Added tests for changed code.
• New features have been added to our Hypothesis testing strategy.
• Changes or additions to public APIs are reflected in our type stubs (files ending in .pyi).
  • ...and used in the stub test file tests/typing_example.py.
• Updated documentation for changed code.
  • New functions/classes have to be added to docs/api.rst by hand.
  • Changes to the signature of @attr.s() have to be added by hand too.
  • Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives. Find the appropriate next version in our __init__.py file.
• Documentation in .rst files is written using semantic newlines.
• Changes (and possible deprecations) have news fragments in changelog.d.

If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

[asford]

Follow-up to #676
Maybe relevant to #668

I had a few free moments to begin reading on the very nice next-gen APIs, but found the main documentation somewhat confusing. My read of the behavior "as documented" was somewhat dismayed, as I often define extra behavior for annotated classes with a small number of annotated attr.ibs. The behavior "as tested" was, gladly, what I expected.

[hynek]

makes sense!

[hynek]

thanks!