Update the documentation for FielSystemEntity.resolveSymbolicLinks

sdk/lib/io/file_system_entity.dart

Index: sdk/lib/io/file_system_entity.dart
diff --git a/sdk/lib/io/file_system_entity.dart b/sdk/lib/io/file_system_entity.dart
index 2c43295894a4fddb5c82dea0219cbfe5b87d1bc7..ee4312fbe9ac72042f194134da3ba0c676058f23 100644
--- a/sdk/lib/io/file_system_entity.dart
+++ b/sdk/lib/io/file_system_entity.dart
@@ -269,22 +269,30 @@ abstract class FileSystemEntity {
   /**
    * Resolves the path of a file system object relative to the
    * current working directory, resolving all symbolic links on
-   * the path and resolving all '..' and '.' path segments.
-   * [resolveSymbolicLinks] returns a [:Future<String>:]
-   *
-   * [resolveSymbolicLinks] uses the operating system's native filesystem api
-   * to resolve the path, using the realpath function on linux and
-   * Mac OS, and the GetFinalPathNameByHandle function on Windows.
-   * If the path does not point to an existing file system object,
-   * [resolveSymbolicLinks] completes the returned Future with an FileSystemException.
-   *
-   * On Windows, symbolic links are resolved to their target before applying
-   * a '..' that follows, and on other platforms, the '..' is applied to the
-   * symbolic link without resolving it.  The second behavior can be emulated
-   * on Windows by processing any '..' segments before calling
-   * [resolveSymbolicLinks].  One way of doing this is with the URI class:
-   * [:new Uri.parse('.').resolveUri(new Uri.file(input)).toFilePath();],
-   * since [resolve] removes '..' segments.
+   * the path and resolving all `..` and `.` path segments.
+   *
+   * [resolveSymbolicLinks] uses the operating system's native
+   * file system API to resolve the path, using the `realpath` function
+   * on linux and Mac OS, and the `GetFinalPathNameByHandle` function on
+   * Windows. If the path does not point to an existing file system object,
+   * `resolveSymbolicLinks` throws a `FileSystemException`.
+   *
+   * On Windows the `..` segments are resolved _before_ resolving the symbolic
+   * link, and on other platforms the symbolic links are _resolved to their
+   * target_ before applying a `..` that follows.
+   *
+   * To ensure the same behavior on all platforms resolve `..` segments before
+   * calling `resolveSymbolicLinks`. One way of doing this is with the `Uri`
+   * class:
+   *
+   *     var path = Uri.parse('.').resolveUri(new Uri.file(input)).toFilePath();
+   *     if (path == '') path = '.';
+   *     new File(path).resolveSymbolicLinks().then((resolved) {
+   *       print(resolved);
+   *     });
+   *
+   * since `Uri.resolve` removes `..` segments. This will result in the Windows
+   * behavior.
    */
   Future<String> resolveSymbolicLinks() {
     return _IOService.dispatch(_FILE_RESOLVE_SYMBOLIC_LINKS, [path])
@@ -301,21 +309,29 @@ abstract class FileSystemEntity {
   /**
    * Resolves the path of a file system object relative to the
    * current working directory, resolving all symbolic links on
-   * the path and resolving all '..' and '.' path segments.
+   * the path and resolving all `..` and `.` path segments.
    *
    * [resolveSymbolicLinksSync] uses the operating system's native
-   * filesystem api to resolve the path, using the realpath function
-   * on linux and Mac OS, and the GetFinalPathNameByHandle function on Windows.
-   * If the path does not point to an existing file system object,
-   * [resolveSymbolicLinksSync] throws a FileSystemException.
-   *
-   * On Windows, symbolic links are resolved to their target before applying
-   * a '..' that follows, and on other platforms, the '..' is applied to the
-   * symbolic link without resolving it.  The second behavior can be emulated
-   * on Windows by processing any '..' segments before calling
-   * [resolveSymbolicLinks].  One way of doing this is with the URI class:
-   * [:new Uri.parse('.').resolveUri(new Uri.file(input)).toFilePath();],
-   * since [resolve] removes '..' segments.
+   * file system API to resolve the path, using the `realpath` function
+   * on linux and Mac OS, and the `GetFinalPathNameByHandle` function on
+   * Windows. If the path does not point to an existing file system object,
+   * `resolveSymbolicLinksSync` throws a `FileSystemException`.
+   *
+   * On Windows the `..` segments are resolved _before_ resolving the symbolic
+   * link, and on other platforms the symbolic links are _resolved to their
+   * target_ before applying a `..` that follows.
+   *
+   * To ensure the same behavior on all platforms resolve `..` segments before
+   * calling `resolveSymbolicLinksSync`. One way of doing this is with the `Uri`
+   * class:
+   *
+   *     var path = Uri.parse('.').resolveUri(new Uri.file(input)).toFilePath();
+   *     if (path == '') path = '.';
+   *     var resolved = new File(path).resolveSymbolicLinksSync();
+   *     print(resolved);
+   *
+   * since `Uri.resolve` removes `..` segments. This will result in the Windows
+   * behavior.
    */
   String resolveSymbolicLinksSync() {
     var result = _resolveSymbolicLinks(path);