API self-documentation

[tobyzerner]

$type->attribute('firstName')
    ->type('string')
    ->description("The user's first name.");

$type->attribute('createdAt')
    ->type(DateTime::class)
    ->description('The time at which the user was created.');

[tobyzerner]

Part of this is attribute types. Perhaps this could be done with alias methods that define a type description, validator, ± a transformer:

$type->attribute('firstName')
    ->required()
    ->string();

// behind the scenes, equivalent to:
$type->attribute('firstName')
    ->validate(function ($fail, $value) {
        if (empty($value)) {
            $fail('This field is required');
        }
    })
    ->type('string')
    ->validate(function ($fail, $value) {
        if (! is_string($value)) {
            $fail('This field must be a string');
        }
    });

$type->attribute('updatedAt')
    ->datetime();

// behind the scenes, equivalent to:
$type->attribute('updatedAt')
    ->type('datetime')
    ->validate(function ($fail, $value) {
        if (! DateTime::createFromFormat(DateTime::ISO8601, $value)) {
            $fail('This field must be a date in ISO8601 format');
        }
    })
    ->transform(function ($value) {
        return DateTime::createFromFormat(DateTime::ISO8601, $value);
    });

$type->attribute('status')
    ->enum(['draft', 'active', 'archived']);

// behind the scenes, equivalent to:
$type->attribute('updatedAt')
    ->type("'draft' | 'active' | 'archived'")
    ->validate(function ($fail, $value) {
        if (! in_array($value, ['draft', 'active', 'archived'])) {
            $fail('Must be one of: draft, active, archived');
        }
    });

[tobyzerner]

Some changes will also be necessary to allow endpoint documentation:

$type->listable()
    ->description('blah')
    ->meta('foo', 'bar');

[tobyzerner]

Closing in favour of #62