Improve documentation

README.md

@@ -40,3 +40,43 @@ $composerJson = file_get_contents('composer.json');
 $composerJson = Indentation::change($composerJson, new Indentation(Indentation::TYPE_TAB, 1));
 file_put_contents('composer.json', $composerJson);
 ```
+
+## Detection Algorithm
+
+The current algorithm looks for the most common difference between two consecutive non-empty lines.
+
+In the following example, even if the 4-space indentation is used 3 times whereas the 2-space one is used 2 times, it is detected as less used because there were only 2 differences with this value instead of 4 for the 2-space indentation:
+
+```css
+html {
+  box-sizing: border-box;
+}
+
+body {
+  background: gray;
+}
+
+p {
+    line-height: 1.3em;
+    margin-top: 1em;
+    text-indent: 2em;
+}
+```
+
+[Source.](https://medium.com/@heatherarthur/detecting-code-indentation-eff3ed0fb56b#3918)
+
+Furthermore, if there are more than one most used difference, the indentation with the most lines is selected.
+
+In the following example, the indentation is detected as 4-spaces:
+
+```css
+body {
+  background: gray;
+}
+
+p {
+    line-height: 1.3em;
+    margin-top: 1em;
+    text-indent: 2em;
+}
+```

src/Indentation.php

@@ -7,7 +7,7 @@
  *
  * (c) Colin O'Dell <colinodell@gmail.com>
  *
- * Forked from detect-indent,
+ * detect() method forked from detect-indent,
  * (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
  *
  * For the full copyright and license information, please view the LICENSE
@@ -82,6 +82,9 @@ public static function detect(string $string): Indentation
         return new self($amount, $type);
     }
 
+    /**
+     * Change the indentation from one style to another
+     */
     public static function change(string $string, Indentation $newStyle): string
     {
         $oldStyle = self::detect($string);