Documentation

Author: steevanb

docs/source/components.rst

@@ -1,42 +1,19 @@
 Components
 ==========
 
-PHP++ id a set of reusable components. You can use all of them of just the one you need.
+PHP++ est un ensemble de composants.
 
-Contracts components
---------------------
-
-When it's possible, a component has it's counterpart ``-contract`` with only interfaces.
-
-If you don't need to use our implementation of this interfaces
-(you just need a typehint, you want to create your own implementation etc),
-use the ``-contract`` dependency and work with interfaces.
-
-Example:
-
-.. code-block:: php
-    :emphasize-lines: 4
-
-    <?php
-    // If you need a StringCollection to work with it,
-    // don't use StringCollection but StringCollectionInterface
-    function foo(StringCollectionInterface $strings): void
-    {
-        // Do some stuff here with $strings
-    }
+Vous pouvez utiliser chaque composant séparément, aucun composant n'est obligatoire :
+c'est à vous de décider d'installer ce dont vous avez besoin !
 
 Components
 ----------
 
-+----------------------+--------------------------------------------+
-| Component            | Description                                |
-+======================+============================================+
-| collection           | Replace array by a strict typed collection |
-+----------------------+--------------------------------------------+
-| collection-contracts | Contracts for collection                   |
-+----------------------+--------------------------------------------+
-| collection-generator | Helps you to generate a Collection         |
-+----------------------+--------------------------------------------+
++-------------------------------------------------+----------------------------------------------------------+
+| Component                                       | Description                                              |
++=================================================+==========================================================+
+| `collection <component/collection/index.html>`_ | Modèle objet pour remlacer ``array`` par une liste typée |
++-------------------------------------------------+----------------------------------------------------------+
 
 Development components
 ----------------------

docs/source/contracts.rst

@@ -0,0 +1,47 @@
+Contracts
+---------
+
+Quand c'est possible, un composant n'est qu'une implémentation d'interfaces.
+
+Ces interfaces se trouvent dans un repository qui a le même nom que le composant, avec le suffixe ``-contract``.
+
+Vous pouvez créer votre propre implémentation tant que vous respectez tous les contrats.
+
+Composants avec des contrats
+----------------------------
+
++-------------------------------------------------+-------------------------------------------------------------+
+| Composant                                       | Contrat                                                     |
++=================================================+=============================================================+
+| `collection <component/collection/index.html>`_ | `collection-contract <component/collection/contract.html>`_ |
++-------------------------------------------------+-------------------------------------------------------------+
+
+Example d'utilisation
+---------------------
+
+Si vous utilisez le composant `collection <component/collection/index.html>`_,
+vous pouvez typer un paramètre avec ``StringCollection``.
+
+Cette façon de typer votre paramètre forcera l'appelant à utiliser
+une certaine implémentation du contrat ``StringCollectionInterface``, alors que vous n'avez peut-être pas besoin
+de cette implémentation très précisément.
+
+Il vaut alors mieux utiliser ``StringCollectionInterface`` comme typage, pour laisser à l'appelant le choix d'utiliser
+l'implémentation qu'il veut.
+Dans ce cas, vous pouvez également installer la dépendance
+`php-pp/collection-contract <https://github.com/php-pp/collection-contract>`_ et pas
+`php-pp/collection <https://github.com/php-pp/collection>`_.
+
+.. code-block:: php
+    :emphasize-lines: 4
+
+    <?php
+    // Vous forcez l'utilisation de StringCollection
+    function foo(StringCollection $strings): void
+    {
+    }
+
+    // Vous laissez le choix à l'appelant d'utiliser l'implémentation qu'il veut
+    function bar(StringCollectionInterface $strings): void
+    {
+    }

docs/source/index.rst

@@ -34,6 +34,7 @@ Contents
    :hidden:
 
    components
+   contracts
 
 .. toctree::
    :caption: Components