commit 977ae22f292406dc91c60798dbf941a985a78302
author James Lin <jamesdlin@google.com> Mon Jun 17 12:32:00 2019 +0000
committer commit-bot@chromium.org <commit-bot@chromium.org> Mon Jun 17 12:32:00 2019 +0000
tree d11958de95152b29d4563e547820151a238bd8fc
parent 43382ded6d8fcc5c75189e1aad9de14da0ec55c6

Make FileStat.stat's dartdoc provide a reference to FileSystemEntityType

Make the documentation to Filestat.stat (and similar functions)
provide a dartdoc reference to FileSystemEntityType.  Also adjust the
formatting of some other identifiers in comments.

Change-Id: I2af58e1c82136ef3ba1414b6f57c59fd8487d282
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/94982
Reviewed-by: Lasse R.H. Nielsen <lrn@google.com>
Reviewed-by: Jonas Termansen <sortie@google.com>
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>
Auto-Submit: James Lin <jamesdlin@google.com>

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 17b05ce..16e99e6 100644
--- a/sdk/lib/io/file_system_entity.dart
+++ b/sdk/lib/io/file_system_entity.dart
@@ -81,9 +81,9 @@
   final DateTime accessed;
 
   /**
-   * The type of the object (file, directory, or link).
+   * The type of the underlying file system object.
    *
-   * If the call to stat() fails, the type of the returned object is notFound.
+   * [FileSystemEntityType.notFound] if [stat] or [statSync] failed.
    */
   final FileSystemEntityType type;
 
@@ -114,11 +114,11 @@
   external static _statSync(_Namespace namespace, String path);
 
   /**
-   * Calls the operating system's stat() function on [path].
+   * Calls the operating system's `stat()` function (or equivalent) on [path].
    *
-   * Returns a [FileStat] object containing the data returned by stat().
-   * If the call fails, returns a [FileStat] object with .type set to
-   * FileSystemEntityType.notFound and the other fields invalid.
+   * Returns a [FileStat] object containing the data returned by `stat()`.
+   * If the call fails, returns a [FileStat] object with [FileStat.type] set to
+   * [FileSystemEntityType.notFound] and the other fields invalid.
    */
   static FileStat statSync(String path) {
     final IOOverrides overrides = IOOverrides.current;
@@ -145,12 +145,10 @@
   }
 
   /**
-   * Asynchronously calls the operating system's stat() function on [path].
+   * Asynchronously calls the operating system's `stat()` function (or
+   * equivalent) on [path].
    *
-   * Returns a Future which completes with a [FileStat] object containing
-   * the data returned by stat(). If the call fails, completes the future with a
-   * [FileStat] object with `.type` set to FileSystemEntityType.notFound and
-   * the other fields invalid.
+   * Returns a [Future] which completes with the same results as [statSync].
    */
   static Future<FileStat> stat(String path) {
     final IOOverrides overrides = IOOverrides.current;
@@ -408,8 +406,8 @@
    * stat().
    *
    * If the call fails, completes the future with a [FileStat] object
-   * with .type set to
-   * FileSystemEntityType.notFound and the other fields invalid.
+   * with `.type` set to [FileSystemEntityType.notFound] and the other fields
+   * invalid.
    */
   Future<FileStat> stat() => FileStat.stat(path);
 
@@ -421,8 +419,8 @@
    *
    * Returns a [FileStat] object containing the data returned by stat().
    *
-   * If the call fails, returns a [FileStat] object with .type set to
-   * FileSystemEntityType.notFound and the other fields invalid.
+   * If the call fails, returns a [FileStat] object with `.type` set to
+   * [FileSystemEntityType.notFound] and the other fields invalid.
    */
   FileStat statSync() => FileStat.statSync(path);
 
@@ -670,15 +668,8 @@
   /**
    * Finds the type of file system object that a path points to.
    *
-   * Returns a [:Future<FileSystemEntityType>:] that completes with the result.
-   *
-   * [FileSystemEntityType] has the constant instances file, directory,
-   * link, and notFound.  [type] will return link only if the optional
-   * named argument [followLinks] is false, and [path] points to a link.
-   * If the path does not point to a file system object, or any other error
-   * occurs in looking up the path, notFound is returned.  The only
-   * error or exception that may be put on the returned future is ArgumentError,
-   * caused by passing the wrong type of arguments to the function.
+   * Returns a [:Future<FileSystemEntityType>:] that completes with the same
+   * results as [typeSync].
    */
   static Future<FileSystemEntityType> type(String path,
       {bool followLinks: true}) {
@@ -690,13 +681,11 @@
    *
    * Returns a [FileSystemEntityType].
    *
-   * [FileSystemEntityType] has the constant instances file, directory,
-   * link, and notFound.  [type] will return link only if the optional
-   * named argument [followLinks] is false, and [path] points to a link.
-   * If the path does not point to a file system object, or any other error
-   * occurs in looking up the path, notFound is returned.  The only
-   * error or exception that may be thrown is ArgumentError,
-   * caused by passing the wrong type of arguments to the function.
+   * Returns [FileSystemEntityType.link] only if [followLinks] is false and if
+   * [path] points to a link.
+   *
+   * Returns [FileSystemEntityType.notFound] if [path] does not point to a file
+   * system object or if any other error occurs in looking up the path.
    */
   static FileSystemEntityType typeSync(String path, {bool followLinks: true}) {
     return _getTypeSync(_toUtf8Array(path), followLinks);