Apply feedback

Author: theofidry

components/filesystem.rst

@@ -250,7 +250,7 @@ Its behavior is the following::
 .. note::
 
     If you wish to canonicalize the path without checking its existence, you can
-    use :method:`Symfony\\Component\\Filesystem\\Path::canonicalize` instead.
+    use :method:`Symfony\\Component\\Filesystem\\Path::canonicalize` method instead.
 
 ``makePathRelative``
 ~~~~~~~~~~~~~~~~~~~~
@@ -354,13 +354,8 @@ those issues.
 Canonicalization
 ~~~~~~~~~~~~~~~~
 
-*Canonicalization* is the transformation of a path into a normalized (the
-"canonical") format. You can canonicalize a path with :method:`Symfony\\Component\\Filesystem\\Path::canonicalize`::
-
-    echo Path::canonicalize('/var/www/vhost/webmozart/../config.ini');
-    // => /var/www/vhost/config.ini
-
-The following modifications happen during canonicalization:
+Returns the shortest path name equivalent to the given path. It applies the
+following rules iteratively until no further processing can be done:
 
 - "." segments are removed;
 - ".." segments are resolved;
@@ -370,9 +365,14 @@ The following modifications happen during canonicalization:
 - schemes (such as "phar://") are kept;
 - replace "~" with the user's home directory.
 
-You can pass absolute paths and relative paths to :method:`Symfony\\Component\\Filesystem\\Path::canonicalize`.
-When a relative path is passed, ".." segments at the beginning of the path are
-kept::
+You can canonicalize a path with :method:`Symfony\\Component\\Filesystem\\Path::canonicalize`::
+
+    echo Path::canonicalize('/var/www/vhost/webmozart/../config.ini');
+    // => /var/www/vhost/config.ini
+
+You can pass absolute paths and relative paths to the
+:method:`Symfony\\Component\\Filesystem\\Path::canonicalize` method. When a
+relative path is passed, ".." segments at the beginning of the path are kept::
 
     echo Path::canonicalize('../uploads/../config/config.yaml');
     // => ../config/config.yaml
@@ -389,8 +389,8 @@ Absolute/relative paths can be converted with the methods
 :method:`Symfony\\Component\\Filesystem\\Path::makeAbsolute`
 and :method:`Symfony\\Component\\Filesystem\\Path::makeRelative`.
 
-:method:`Symfony\\Component\\Filesystem\\Path::makeAbsolute` expects a relative
-path and a base path to base that relative path upon::
+:method:`Symfony\\Component\\Filesystem\\Path::makeAbsolute` method expects a
+relative path and a base path to base that relative path upon::
 
     echo Path::makeAbsolute('config/config.yaml', '/var/www/project');
     // => /var/www/project/config/config.yaml