Add normalizer/denormalizer interface descriptions

Author: Kirill Nesmeyanov

src/DenormalizerInterface.php

@@ -5,16 +5,33 @@
 namespace TypeLang\Mapper;
 
 use JetBrains\PhpStorm\Language;
+use TypeLang\Mapper\Exception\Definition\TypeNotFoundException;
 
 interface DenormalizerInterface
 {
     /**
+     * Denormalizes a specific type from generic data.
+     *
+     * Can be used to convert to PHP values from an external data source
+     * such as JSON, MessagePack, BSON, etc.
+     *
+     * ```
+     * $denormalizer->denormalize(\json_decode('{
+     *     "id": 42,
+     *     "name": "Kirill"
+     * }'), ExampleClass::class);
+     * ```
+     *
      * @param non-empty-string $type
      */
     public function denormalize(mixed $value, #[Language('PHP')] string $type): mixed;
 
     /**
+     * Returns {@see true} if the value can be denormalized for the given type.
+     *
      * @param non-empty-string $type
+     * @throws TypeNotFoundException in case of type not found
+     * @throws \Throwable in case of any internal error occurs
      */
     public function isDenormalizable(mixed $value, #[Language('PHP')] string $type): bool;
 }

src/NormalizerInterface.php

@@ -5,16 +5,39 @@
 namespace TypeLang\Mapper;
 
 use JetBrains\PhpStorm\Language;
+use TypeLang\Mapper\Exception\Definition\TypeNotFoundException;
 
 interface NormalizerInterface
 {
     /**
+     * Normalizes a specific value to generic data.
+     *
+     * Can be used to convert to structural data (for JSON, BSON, MessagePack, etc)
+     * from an PHP values.
+     *
+     * In case that the type is specified as {@see null}, it is automatically
+     * inferred from the passed value.
+     *
+     * ```
+     * $normalizer->normalize(new ExampleClass(
+     *     id: 42,
+     *     name: 'Kirill',
+     * ));
+     * ```
+     *
      * @param non-empty-string|null $type
      */
     public function normalize(mixed $value, #[Language('PHP')] ?string $type = null): mixed;
 
     /**
+     * Returns {@see true} if the value can be normalized for the given type.
+     *
+     * In case that the type is specified as {@see null}, it is automatically
+     * inferred from the passed value.
+     *
      * @param non-empty-string|null $type
+     * @throws TypeNotFoundException in case of type not found
+     * @throws \Throwable in case of any internal error occurs
      */
     public function isNormalizable(mixed $value, #[Language('PHP')] ?string $type = null): bool;
 }