Add documentation on top of classes (#924)

* Add documentation on top of classes

* Add changelog

* remove debug code

Author: jderusse

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## NOT RELEASED
 
+### Added
+
+- Added documentation in class's headers.
+
 ## 1.0.1
 
 ### Fixed

src/Enum/AttributeAction.php

@@ -2,6 +2,50 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * Specifies how to perform the update. Valid values are `PUT` (default), `DELETE`, and `ADD`. The behavior depends on
+ * whether the specified primary key already exists in the table.
+ * **If an item with the specified *Key* is found in the table:**.
+ *
+ * - `PUT` - Adds the specified attribute to the item. If the attribute already exists, it is replaced by the new value.
+ * - `DELETE` - If no value is specified, the attribute and its value are removed from the item. The data type of the
+ *   specified value must match the existing value's data type.
+ *   If a *set* of values is specified, then those values are subtracted from the old set. For example, if the attribute
+ *   value was the set `[a,b,c]` and the `DELETE` action specified `[a,c]`, then the final attribute value would be
+ *   `[b]`. Specifying an empty set is an error.
+ * - `ADD` - If the attribute does not already exist, then the attribute and its values are added to the item. If the
+ *   attribute does exist, then the behavior of `ADD` depends on the data type of the attribute:
+ *
+ *   - If the existing attribute is a number, and if `Value` is also a number, then the `Value` is mathematically added
+ *     to the existing attribute. If `Value` is a negative number, then it is subtracted from the existing attribute.
+ *
+ *     > If you use `ADD` to increment or decrement a number value for an item that doesn't exist before the update,
+ *     > DynamoDB uses 0 as the initial value.
+ *     > In addition, if you use `ADD` to update an existing item, and intend to increment or decrement an attribute
+ *     > value which does not yet exist, DynamoDB uses `0` as the initial value. For example, suppose that the item you
+ *     > want to update does not yet have an attribute named *itemcount*, but you decide to `ADD` the number `3` to this
+ *     > attribute anyway, even though it currently does not exist. DynamoDB will create the *itemcount* attribute, set
+ *     > its initial value to `0`, and finally add `3` to it. The result will be a new *itemcount* attribute in the
+ *     > item, with a value of `3`.
+ *
+ *   - If the existing data type is a set, and if the `Value` is also a set, then the `Value` is added to the existing
+ *     set. (This is a *set* operation, not mathematical addition.) For example, if the attribute value was the set
+ *     `[1,2]`, and the `ADD` action specified `[3]`, then the final attribute value would be `[1,2,3]`. An error occurs
+ *     if an Add action is specified for a set attribute and the attribute type specified does not match the existing
+ *     set type.
+ *     Both sets must have the same primitive data type. For example, if the existing data type is a set of strings, the
+ *     `Value` must also be a set of strings. The same holds true for number sets and binary sets.
+ *
+ *   This action is only valid for an existing attribute whose data type is number or is a set. Do not use `ADD` for any
+ *   other data types.
+ *
+ * **If no item with the specified *Key* is found:**
+ *
+ * - `PUT` - DynamoDB creates a new item with the specified primary key, and then adds the attribute.
+ * - `DELETE` - Nothing happens; there is no attribute to delete.
+ * - `ADD` - DynamoDB creates an item with the supplied primary key and number (or set of numbers) for the attribute
+ *   value. The only data types allowed are number and number set; no other data types can be specified.
+ */
 final class AttributeAction
 {
     public const ADD = 'ADD';

src/Enum/BillingMode.php

@@ -2,6 +2,18 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * Controls how you are charged for read and write throughput and how you manage capacity. This setting can be changed
+ * later.
+ *
+ * - `PROVISIONED` - We recommend using `PROVISIONED` for predictable workloads. `PROVISIONED` sets the billing mode to
+ *   Provisioned Mode.
+ * - `PAY_PER_REQUEST` - We recommend using `PAY_PER_REQUEST` for unpredictable workloads. `PAY_PER_REQUEST` sets the
+ *   billing mode to On-Demand Mode.
+ *
+ * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html#HowItWorks.ProvisionedThroughput.Manual
+ * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html#HowItWorks.OnDemand
+ */
 final class BillingMode
 {
     public const PAY_PER_REQUEST = 'PAY_PER_REQUEST';

src/Enum/ComparisonOperator.php

@@ -2,6 +2,86 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * A comparator for evaluating attributes in the `AttributeValueList`. For example, equals, greater than, less than,
+ * etc.
+ * The following comparison operators are available:
+ * `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
+ * The following are descriptions of each comparison operator.
+ *
+ * - `EQ` : Equal. `EQ` is supported for all data types, including lists and maps.
+ *   `AttributeValueList` can contain only one `AttributeValue` element of type String, Number, Binary, String Set,
+ *   Number Set, or Binary Set. If an item contains an `AttributeValue` element of a different type than the one
+ *   provided in the request, the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also,
+ *   `{"N":"6"}` does not equal `{"NS":["6", "2", "1"]}`.
+ * - `NE` : Not equal. `NE` is supported for all data types, including lists and maps.
+ *   `AttributeValueList` can contain only one `AttributeValue` of type String, Number, Binary, String Set, Number Set,
+ *   or Binary Set. If an item contains an `AttributeValue` of a different type than the one provided in the request,
+ *   the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not equal
+ *   `{"NS":["6", "2", "1"]}`.
+ * - `LE` : Less than or equal.
+ *   `AttributeValueList` can contain only one `AttributeValue` element of type String, Number, or Binary (not a set
+ *   type). If an item contains an `AttributeValue` element of a different type than the one provided in the request,
+ *   the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not compare
+ *   to `{"NS":["6", "2", "1"]}`.
+ * - `LT` : Less than.
+ *   `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set type). If
+ *   an item contains an `AttributeValue` element of a different type than the one provided in the request, the value
+ *   does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not compare to
+ *   `{"NS":["6", "2", "1"]}`.
+ * - `GE` : Greater than or equal.
+ *   `AttributeValueList` can contain only one `AttributeValue` element of type String, Number, or Binary (not a set
+ *   type). If an item contains an `AttributeValue` element of a different type than the one provided in the request,
+ *   the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not compare
+ *   to `{"NS":["6", "2", "1"]}`.
+ * - `GT` : Greater than.
+ *   `AttributeValueList` can contain only one `AttributeValue` element of type String, Number, or Binary (not a set
+ *   type). If an item contains an `AttributeValue` element of a different type than the one provided in the request,
+ *   the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not compare
+ *   to `{"NS":["6", "2", "1"]}`.
+ * - `NOT_NULL` : The attribute exists. `NOT_NULL` is supported for all data types, including lists and maps.
+ *
+ *   > This operator tests for the existence of an attribute, not its data type. If the data type of attribute "`a`" is
+ *   > null, and you evaluate it using `NOT_NULL`, the result is a Boolean `true`. This result is because the attribute
+ *   > "`a`" exists; its data type is not relevant to the `NOT_NULL` comparison operator.
+ *
+ * - `NULL` : The attribute does not exist. `NULL` is supported for all data types, including lists and maps.
+ *
+ *   > This operator tests for the nonexistence of an attribute, not its data type. If the data type of attribute "`a`"
+ *   > is null, and you evaluate it using `NULL`, the result is a Boolean `false`. This is because the attribute "`a`"
+ *   > exists; its data type is not relevant to the `NULL` comparison operator.
+ *
+ * - `CONTAINS` : Checks for a subsequence, or value in a set.
+ *   `AttributeValueList` can contain only one `AttributeValue` element of type String, Number, or Binary (not a set
+ *   type). If the target attribute of the comparison is of type String, then the operator checks for a substring match.
+ *   If the target attribute of the comparison is of type Binary, then the operator looks for a subsequence of the
+ *   target that matches the input. If the target attribute of the comparison is a set ("`SS`", "`NS`", or "`BS`"), then
+ *   the operator evaluates to true if it finds an exact match with any member of the set.
+ *   CONTAINS is supported for lists: When evaluating "`a CONTAINS b`", "`a`" can be a list; however, "`b`" cannot be a
+ *   set, a map, or a list.
+ * - `NOT_CONTAINS` : Checks for absence of a subsequence, or absence of a value in a set.
+ *   `AttributeValueList` can contain only one `AttributeValue` element of type String, Number, or Binary (not a set
+ *   type). If the target attribute of the comparison is a String, then the operator checks for the absence of a
+ *   substring match. If the target attribute of the comparison is Binary, then the operator checks for the absence of a
+ *   subsequence of the target that matches the input. If the target attribute of the comparison is a set ("`SS`",
+ *   "`NS`", or "`BS`"), then the operator evaluates to true if it *does not* find an exact match with any member of the
+ *   set.
+ *   NOT_CONTAINS is supported for lists: When evaluating "`a NOT CONTAINS b`", "`a`" can be a list; however, "`b`"
+ *   cannot be a set, a map, or a list.
+ * - `BEGINS_WITH` : Checks for a prefix.
+ *   `AttributeValueList` can contain only one `AttributeValue` of type String or Binary (not a Number or a set type).
+ *   The target attribute of the comparison must be of type String or Binary (not a Number or a set type).
+ * - `IN` : Checks for matching elements in a list.
+ *   `AttributeValueList` can contain one or more `AttributeValue` elements of type String, Number, or Binary. These
+ *   attributes are compared against an existing attribute of an item. If any elements of the input are equal to the
+ *   item attribute, the expression evaluates to true.
+ * - `BETWEEN` : Greater than or equal to the first value, and less than or equal to the second value.
+ *   `AttributeValueList` must contain two `AttributeValue` elements of the same type, either String, Number, or Binary
+ *   (not a set type). A target attribute matches if the target value is greater than, or equal to, the first element
+ *   and less than, or equal to, the second element. If an item contains an `AttributeValue` element of a different type
+ *   than the one provided in the request, the value does not match. For example, `{"S":"6"}` does not compare to
+ *   `{"N":"6"}`. Also, `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`
+ */
 final class ComparisonOperator
 {
     public const BEGINS_WITH = 'BEGINS_WITH';

src/Enum/ConditionalOperator.php

@@ -2,6 +2,12 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * This is a legacy parameter. Use `ConditionExpression` instead. For more information, see ConditionalOperator in the
+ * *Amazon DynamoDB Developer Guide*.
+ *
+ * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.ConditionalOperator.html
+ */
 final class ConditionalOperator
 {
     public const AND = 'AND';

src/Enum/IndexStatus.php

@@ -2,6 +2,14 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * The current state of the global secondary index:.
+ *
+ * - `CREATING` - The index is being created.
+ * - `UPDATING` - The index is being updated.
+ * - `DELETING` - The index is being deleted.
+ * - `ACTIVE` - The index is ready for use.
+ */
 final class IndexStatus
 {
     public const ACTIVE = 'ACTIVE';

src/Enum/KeyType.php

@@ -2,6 +2,18 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * The role that this key attribute will assume:.
+ *
+ * - `HASH` - partition key
+ * - `RANGE` - sort key
+ *
+ * > The partition key of an item is also known as its *hash attribute*. The term "hash attribute" derives from
+ * > DynamoDB's usage of an internal hash function to evenly distribute data items across partitions, based on their
+ * > partition key values.
+ * > The sort key of an item is also known as its *range attribute*. The term "range attribute" derives from the way
+ * > DynamoDB stores items with the same partition key physically close together, in sorted order by the sort key value.
+ */
 final class KeyType
 {
     public const HASH = 'HASH';

src/Enum/ProjectionType.php

@@ -2,6 +2,14 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * The set of attributes that are projected into the index:.
+ *
+ * - `KEYS_ONLY` - Only the index and primary keys are projected into the index.
+ * - `INCLUDE` - In addition to the attributes described in `KEYS_ONLY`, the secondary index will include other non-key
+ *   attributes that you specify.
+ * - `ALL` - All of the table attributes are projected into the index.
+ */
 final class ProjectionType
 {
     public const ALL = 'ALL';

src/Enum/ReplicaStatus.php

@@ -2,6 +2,23 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * The current state of the replica:.
+ *
+ * - `CREATING` - The replica is being created.
+ * - `UPDATING` - The replica is being updated.
+ * - `DELETING` - The replica is being deleted.
+ * - `ACTIVE` - The replica is ready for use.
+ * - `REGION_DISABLED` - The replica is inaccessible because the AWS Region has been disabled.
+ *
+ *   > If the AWS Region remains inaccessible for more than 20 hours, DynamoDB will remove this replica from the
+ *   > replication group. The replica will not be deleted and replication will stop from and to this region.
+ *
+ * - `INACCESSIBLE_ENCRYPTION_CREDENTIALS ` - The AWS KMS key used to encrypt the table is inaccessible.
+ *
+ *   > If the AWS KMS key remains inaccessible for more than 20 hours, DynamoDB will remove this replica from the
+ *   > replication group. The replica will not be deleted and replication will stop from and to this region.
+ */
 final class ReplicaStatus
 {
     public const ACTIVE = 'ACTIVE';

src/Enum/ReturnItemCollectionMetrics.php

@@ -2,6 +2,11 @@
 
 namespace AsyncAws\DynamoDb\Enum;
 
+/**
+ * Determines whether item collection metrics are returned. If set to `SIZE`, the response includes statistics about
+ * item collections, if any, that were modified during the operation are returned in the response. If set to `NONE` (the
+ * default), no statistics are returned.
+ */
 final class ReturnItemCollectionMetrics
 {
     public const NONE = 'NONE';