Update docs with correct nullable information.

Fix bug #14

Author: wol-soft

docs/source/complexTypes/array.rst

@@ -24,7 +24,8 @@ Generated interface:
 
 .. code-block:: php
 
-    public function setExample(?array $example): self;
+    public function setExample(array $example): self;
+    // As the property is not required it may be initialized with null. Consequently the return value is nullable
     public function getExample(): ?array;
 
 Possible exceptions:
@@ -117,17 +118,17 @@ In this case the model generator will generate two classes: **Family** and **Mem
 .. code-block:: php
 
     // class Family
-    public function setMembers(?array $members): self;
+    public function setMembers(array $members): self;
     public function getMembers(): ?array;
 
     // class Member
     public function setName(string $name): self;
     public function getName(): string;
 
-    public function setAge(?int $age): self;
+    public function setAge(int $age): self;
     public function getAge(): ?int;
 
-The *getMembers* function of the class *Family* is typehinted with *@returns Member[]*. Consequently auto completion is available when developing something like:
+The *getMembers* function of the class *Family* is type hinted with *@returns Member[]*. Consequently auto completion is available when developing something like:
 
 .. code-block:: php
 
@@ -138,6 +139,10 @@ The *getMembers* function of the class *Family* is typehinted with *@returns Mem
         $member->getName();
     }
 
+.. hint::
+
+    Arrays with item validation don't accept elements which contain `null`. If your array needs to accept `null` entries you have to add null to the type of your items explicitly (eg. "type": ["object", "null"]).
+
 Tuples
 ------
 

docs/source/complexTypes/multiType.rst

@@ -19,7 +19,9 @@ Generated interface (doesn't contain type hints as multiple types are allowed):
 
 .. code-block:: php
 
+    // $example will be type-annotated with `float|string`
     public function setExample($example): self;
+    // $example will be type-annotated with `float|string|null` (as the property isn't required)
     public function getExample();
 
 Possible exceptions:
@@ -60,6 +62,7 @@ For each type given in the allowed types array additional validators may be adde
         }
     }
 
+The property example will be type hinted with `float|string|string[]|null`.
 The validators are applied if the given input matches the corresponding type.
 For example if an array **["Hello", 123, "Goodbye"]** is given the validation will fail as numbers aren't allowed in arrays:
 

docs/source/complexTypes/object.rst

@@ -32,15 +32,16 @@ Generated interface:
 .. code-block:: php
 
     // class Person
-    public function setName(?string $name): self;
+    public function setName(string $name): self;
+    // As the property is not required it may be initialized with null. Consequently the return value is nullable
     public function getName(): ?string;
-    public function setCar(?Car $name): self;
+    public function setCar(Car $name): self;
     public function getCar(): ?Car;
 
     // class Car
-    public function setModel(?string $name): self;
+    public function setModel(string $name): self;
     public function getModel(): ?string;
-    public function setPs(?int $name): self;
+    public function setPs(int $name): self;
     public function getPs(): ?int;
 
 Possible exceptions:
@@ -102,9 +103,9 @@ Generated interface:
 
 .. code-block:: php
 
-    public function setUnderscorePropertyMinus(?string $name): self;
+    public function setUnderscorePropertyMinus(string $name): self;
     public function getUnderscorePropertyMinus(): ?string;
-    public function setCapsAndSpace100(?string $name): self;
+    public function setCapsAndSpace100(string $name): self;
     public function getCapsAndSpace100(): ?string;
 
 If the name normalization results in an empty attribute name (eg. '__ -- __') an exception will be thrown.
@@ -283,14 +284,14 @@ Generated interface:
 
 .. code-block:: php
 
-    // class Family, arrays typehinted in docblocks with Family_Person[]
-    public function setMembers(?array $members): self;
+    // class Family, arrays type hinted in docblocks with Family_Person[]
+    public function setMembers(array $members): self;
     public function getMembers(): ?array;
 
-    // class Person, arrays typehinted in docblocks with Family_Person[]
-    public function setName(?string $name): self;
+    // class Person, arrays type hinted in docblocks with Family_Person[]
+    public function setName(string $name): self;
     public function getName(): ?string;
-    public function setChildren(?array $name): self;
+    public function setChildren(array $name): self;
     public function getChildren(): ?array;
 
 Property Names
@@ -448,10 +449,11 @@ Generated interface:
 
     // class CreditCardOwner
     // base properties
-    public function setCreditCard(?int $creditCard): self;
+    public function setCreditCard(int $creditCard): self;
     public function getCreditCard(): ?int;
 
     // inherited properties
+    // the inherited properties will not be type hinted as they may contain any value if credit_card isn't present.
     public function setBillingAddress($billingAddress): self;
     public function getBillingAddress();
     public function setDateOfBirth($dateOfBirth): self;

docs/source/generic/required.rst

@@ -1,7 +1,7 @@
 Required values
 ===============
 
-By default the values of a schema are not required. In this case the input is valid if the property is not provided. Additionally an explicit `null` value is also valid. If the value isn't provided an optionally defined default value is used.
+By default the values of a schema are not required. In this case the input is valid if the property is not provided. If the value isn't provided an optionally defined default value is used.
 
 .. code-block:: json
 
@@ -21,7 +21,8 @@ Generated interface:
 
 .. code-block:: php
 
-    public function setExample(?string $example): self;
+    public function setExample(string $example): self;
+    // As the property is not required it may be initialized with null. Consequently the return value is nullable
     public function getExample(): ?string;
 
 Behaviour with different inputs:
@@ -35,6 +36,7 @@ Behaviour with different inputs:
     // property example explicitly set to null.
     // allowed as the property isn't required.
     // Works only if implicitNull is enabled. Otherwise an exception will be thrown.
+    // If implicitNull is enabled the signature of setExample will also change to accept null.
     $example = new Example(['example' => null]);
     $example->getExample();     // returns NULL
 

docs/source/gettingStarted.rst

@@ -161,6 +161,8 @@ By default the properties are strictly checked against their defined types. Cons
 
 By setting the implicit null option to true all of your object properties which aren't required will implicitly accept null. All properties which are required and don't explicitly allow null in the type definition will still reject null.
 
+If the implicit null option is enabled the interface of your classes may change. If you have disabled immutability the type hints of your optional property setters will be nullable (eg. a string property will be type hinted with `?string`).
+
 .. code-block:: php
 
     setImplicitNull(bool $allowImplicitNull);

docs/source/types/boolean.rst

@@ -19,7 +19,8 @@ Generated interface:
 
 .. code-block:: php
 
-    public function setExample(?bool $example): self;
+    public function setExample(bool $example): self;
+    // As the property is not required it may be initialized with null. Consequently the return value is nullable
     public function getExample(): ?bool;
 
 Possible exceptions:

docs/source/types/number.rst

@@ -22,10 +22,11 @@ Generated interface:
 
 .. code-block:: php
 
-    public function setExample1(?int $example): self;
+    public function setExample1(int $example): self;
+    // As the property is not required it may be initialized with null. Consequently the return value is nullable
     public function getExample1(): ?int;
 
-    public function setExample2(?float $example): self;
+    public function setExample2(float $example): self;
     public function getExample2(): ?float;
 
 Possible exceptions:

docs/source/types/string.rst

@@ -19,7 +19,8 @@ Generated interface:
 
 .. code-block:: php
 
-    public function setExample(?string $example): self;
+    public function setExample(string $example): self;
+    // As the property is not required it may be initialized with null. Consequently the return value is nullable
     public function getExample(): ?string;
 
 Possible exceptions:

src/SchemaProvider/RecursiveDirectoryProvider.php

@@ -34,7 +34,7 @@ public function __construct(string $sourceDirectory)
             throw new FileSystemException("Source directory '$sourceDirectory' doesn't exist");
         }
 
-        $this->sourceDirectory = $sourceDirectory;
+        $this->sourceDirectory = rtrim($sourceDirectory, "\\/");
     }
 
     /**