Add description to codec interfaces

Author: alcaeus

src/Codec/Codec.php

@@ -3,6 +3,9 @@
 namespace MongoDB\Codec;
 
 /**
+ * The Codec interface allows decoding BSON data to native PHP types and back
+ * to BSON.
+ *
  * @psalm-template BSONType
  * @psalm-template NativeType
  * @template-extends Decoder<BSONType, NativeType>

src/Codec/Decoder.php

@@ -2,6 +2,8 @@
 
 namespace MongoDB\Codec;
 
+use MongoDB\Exception\InvalidArgumentException;
+
 /**
  * @internal
  * @psalm-template BSONType
@@ -10,20 +12,31 @@
 interface Decoder
 {
     /**
+     * Checks if the decoder supports a given value.
+     *
      * @param mixed $value
      * @psalm-assert-if-true BSONType $value
      */
     public function canDecode($value): bool;
 
     /**
+     * Decodes a given value. If the decoder does not support the value, it
+     * should throw an exception.
+     *
      * @param mixed $value
      * @psalm-param BSONType $value
      * @return mixed
      * @psalm-return NativeType
+     * @throws InvalidArgumentException if the decoder does not support the value
      */
     public function decode($value);
 
     /**
+     * Decodes a given value if supported, otherwise returns the value as-is.
+     *
+     * The DecodeIfSupported trait provides a default implementation of this
+     * method.
+     *
      * @param mixed $value
      * @psalm-param mixed $value
      * @return mixed

src/Codec/DocumentCodec.php

@@ -5,6 +5,9 @@
 use MongoDB\BSON\Document;
 
 /**
+ * The DocumentCodec interface allows decoding BSON document data to native PHP
+ * objects and back to BSON documents.
+ *
  * @psalm-template ObjectType of object
  * @template-extends Codec<Document, ObjectType>
  */

src/Codec/Encoder.php

@@ -2,6 +2,8 @@
 
 namespace MongoDB\Codec;
 
+use MongoDB\Exception\InvalidArgumentException;
+
 /**
  * @internal
  * @psalm-template BSONType
@@ -10,20 +12,31 @@
 interface Encoder
 {
     /**
+     * Checks if the encoder supports a given value.
+     *
      * @param mixed $value
      * @psalm-assert-if-true NativeType $value
      */
     public function canEncode($value): bool;
 
     /**
+     * Encodes a given value. If the encoder does not support the value, it
+     * should throw an exception.
+     *
      * @param mixed $value
      * @psalm-param NativeType $value
      * @return mixed
      * @psalm-return BSONType
+     * @throws InvalidArgumentException if the decoder does not support the value
      */
     public function encode($value);
 
     /**
+     * Encodes a given value if supported, otherwise returns the value as-is.
+     *
+     * The EncodeIfSupported trait provides a default implementation of this
+     * method.
+     *
      * @param mixed $value
      * @psalm-param mixed $value
      * @return mixed

src/Codec/KnowsCodecLibrary.php

@@ -2,6 +2,11 @@
 
 namespace MongoDB\Codec;
 
+/**
+ * This interface is used to indicate that a class is aware of the CodecLibrary
+ * it was added to. The library will be injected when the codec is added to the
+ * library. This allows codecs to recursively encode its nested values.
+ */
 interface KnowsCodecLibrary
 {
     public function attachLibrary(CodecLibrary $library): void;