Update the documentation for FielSystemEntity.resolveSymbolicLinks

sdk/lib/io/file_system_entity.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * The type of an entity on the file system, such as a file, directory, or link.
  *
  * These constants are used by the [FileSystemEntity] class
@@ skipping 251 matching lines @@
    *
    * If [newPath] identifies an existing entity of the same type, that entity
    * is replaced. If [newPath] identifies an existing entity of a different
    * type, the operation fails and an exception is thrown.
    */
   FileSystemEntity renameSync(String newPath);
 
   /**
    * 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>:]
+   * the path and resolving all `..` and `.` path segments.
    *
-   * [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.
+   * [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, 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.
+   * 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])
         .then((response) {
           if (_isErrorResponse(response)) {
             throw _exceptionFromResponse(response,
                                          "Cannot resolve symbolic links",
                                          path);
           }
           return response;
         });
   }
 
   /**
    * 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.
+   * 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, 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.
+   * 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);
     _throwIfError(result, "Cannot resolve symbolic links", path);
     return result;
   }
 
 
   /**
    * Calls the operating system's stat() function on the [path] of this
@@ skipping 479 matching lines @@
     return buffer.toString();
   }
 }
 
 
 class _FileSystemWatcher {
   external static Stream<FileSystemEvent> watch(
       String path, int events, bool recursive);
   external static bool get isSupported;
 }