Document our type-juggling-prevention system

2 files changed, 19 insertions, 2 deletions

diff --git a/doc/source/config.rst b/doc/source/config.rst
index b3495ae..14626ce 100644
--- a/doc/source/config.rst
+++ b/doc/source/config.rst
@@ -109,8 +109,9 @@ It can either be ``enabled`` or ``disabled``.
 Prevent sloppy comparison
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-sloppy_comparison, disabled by default, will prevent php `type
-juggling <https://secure.php.net/manual/en/language.types.type-juggling.php>`_ (``==``) , preventing any bypass of a comparison.
+:ref:`Sloppy comparison prevention <sloppy-comparisons-feature>`, disabled by default, will prevent php `type
+juggling <https://secure.php.net/manual/en/language.types.type-juggling.php>`_ (``==``):
+two values with different types will always be different.
 
 It can either be ``enabled`` or ``disabled``.
 
diff --git a/doc/source/features.rst b/doc/source/features.rst
index e420156..5543696 100644
--- a/doc/source/features.rst
+++ b/doc/source/features.rst
@@ -316,6 +316,22 @@ This feature is largely inspired from the
 `autostrict <https://github.com/krakjoe/autostrict>`_ module from `krakjoe <http://krakjoe.ninja>`__.
 
 
+.. _sloppy-comparisons-feature:
+
+Preventing sloppy comparisons
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The aforementioned :ref:`strict mode <global-strict-feature>` only works with
+annotated types and native functions, so it doesn't cover every instances of
+`type juggling <https://secure.php.net/manual/en/language.types.type-juggling.php>`
+during comparisons. Since comparison between different types in PHP is
+`notoriously <https://secure.php.net/manual/en/types.comparisons.php>`__
+difficult to get right, Snuffleupagus offers a way to **always** use the
+``identical`` operator instead of the ``equal`` one (see the `operator section
+<https://secure.php.net/manual/en/language.operators.comparison.php>` for PHP's documentation
+for more details), so that values with different types will always be treated
+as being different.
+
 .. _readonly-exec-feature:
 
 Preventing execution of writable PHP files