#2291. Update Link.create() tests according to the documentation

LibTest/io/Link/create_A01_t01.dart

@@ -6,33 +6,36 @@
 ///  String target, {
 ///  bool recursive: false
 ///  })
-/// Creates a symbolic link. Returns a Future<Link> that completes with the link
-/// when it has been created. If the link exists, the future will complete with
-/// an error.
+/// Creates a symbolic link in the file system.
 ///
-/// If recursive is false, the default, the link is created only if all
-/// directories in its path exist. If recursive is true, all non-existing path
-/// components are created. The directories in the path of target are not
-/// affected, unless they are also in path.
+/// The created link will point to the path at `target`, whether that path
+/// exists or not.
 ///
-/// On the Windows platform, this will only work with directories, and the target
-/// directory must exist. The link will be created as a Junction. Only absolute
-/// links will be created, and relative paths to the target will be converted to
-/// absolute paths by joining them with the path of the directory the link is
-/// contained in.
+/// Returns a `Future<Link>` that completes with the link when it has been
+/// created. If the link path already exists, the future will complete with an
+/// error.
 ///
-/// On other platforms, the posix symlink() call is used to make a symbolic link
-/// containing the string target. If target is a relative path, it will be
-/// interpreted relative to the directory containing the link.
-/// @description Checks that this method creates the link
+/// If `recursive` is `false`, the default, the link is created only if all
+/// directories in its path exist. If `recursive` is `true`, all non-existing
+/// parent paths are created first. The directories in the path of target are
+/// not affected, unless they are also in [path].
+///
+/// On the Windows platform, this call will create a true symbolic link instead
+/// of a junction. The link represents a file or directory and does not change
+/// its type after creation. If `target` exists then the type of the link will
+/// match the type `target`, otherwise a file symlink is created.
 ///
-/// @note The test should run with the Administrator priveleges on Windows.
-/// Dart API Spec reads:
 /// In order to create a symbolic link on Windows, Dart must be run in
 /// Administrator mode or the system must have Developer Mode enabled, otherwise
-/// a FileSystemException will be raised with ERROR_PRIVILEGE_NOT_HELD set as
-/// the errno when this call is made.
+/// a [FileSystemException] will be raised with `ERROR_PRIVILEGE_NOT_HELD` set
+/// as the errno when this call is made.
+///
+/// On other platforms, the POSIX `symlink()` call is used to make a symbolic
+/// link containing the string `target`. If `target` is a relative path, it will
+/// be interpreted relative to the directory containing the link.
 ///
+/// @description Checks that this method creates the link. Test [Directory] as
+/// a target
 /// @author sgrekhov@unipro.ru
 
 import "dart:io";
@@ -50,6 +53,7 @@ _main(Directory sandbox) async {
   await link.create(target.path).then((Link created) {
     Expect.isTrue(created.existsSync());
     Expect.equals(link.path, created.path);
+    Expect.equals(target.path, created.targetSync());
     asyncEnd();
   });
 }

LibTest/io/Link/create_A01_t02.dart

@@ -0,0 +1,59 @@
+// Copyright (c) 2023, 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.
+
+/// @assertion Future<Link> create(
+///  String target, {
+///  bool recursive: false
+///  })
+/// Creates a symbolic link in the file system.
+///
+/// The created link will point to the path at `target`, whether that path
+/// exists or not.
+///
+/// Returns a `Future<Link>` that completes with the link when it has been
+/// created. If the link path already exists, the future will complete with an
+/// error.
+///
+/// If `recursive` is `false`, the default, the link is created only if all
+/// directories in its path exist. If `recursive` is `true`, all non-existing
+/// parent paths are created first. The directories in the path of target are
+/// not affected, unless they are also in [path].
+///
+/// On the Windows platform, this call will create a true symbolic link instead
+/// of a junction. The link represents a file or directory and does not change
+/// its type after creation. If `target` exists then the type of the link will
+/// match the type `target`, otherwise a file symlink is created.
+///
+/// In order to create a symbolic link on Windows, Dart must be run in
+/// Administrator mode or the system must have Developer Mode enabled, otherwise
+/// a [FileSystemException] will be raised with `ERROR_PRIVILEGE_NOT_HELD` set
+/// as the errno when this call is made.
+///
+/// On other platforms, the POSIX `symlink()` call is used to make a symbolic
+/// link containing the string `target`. If `target` is a relative path, it will
+/// be interpreted relative to the directory containing the link.
+///
+/// @description Checks that this method creates the link. Test [File] as a
+/// target
+/// @author sgrekhov22@gmail.com
+
+import "dart:io";
+import "../../../Utils/expect.dart";
+import "../file_utils.dart";
+
+main() async {
+  await inSandbox(_main);
+}
+
+_main(Directory sandbox) async {
+  File target = getTempFileSync(parent: sandbox);
+  Link link = new Link(getTempFilePath(parent: sandbox));
+  asyncStart();
+  await link.create(target.path).then((Link created) {
+    Expect.isTrue(created.existsSync());
+    Expect.equals(link.path, created.path);
+    Expect.equals(target.path, created.targetSync());
+    asyncEnd();
+  });
+}

LibTest/io/Link/create_A01_t03.dart

@@ -0,0 +1,59 @@
+// Copyright (c) 2023, 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.
+
+/// @assertion Future<Link> create(
+///  String target, {
+///  bool recursive: false
+///  })
+/// Creates a symbolic link in the file system.
+///
+/// The created link will point to the path at `target`, whether that path
+/// exists or not.
+///
+/// Returns a `Future<Link>` that completes with the link when it has been
+/// created. If the link path already exists, the future will complete with an
+/// error.
+///
+/// If `recursive` is `false`, the default, the link is created only if all
+/// directories in its path exist. If `recursive` is `true`, all non-existing
+/// parent paths are created first. The directories in the path of target are
+/// not affected, unless they are also in [path].
+///
+/// On the Windows platform, this call will create a true symbolic link instead
+/// of a junction. The link represents a file or directory and does not change
+/// its type after creation. If `target` exists then the type of the link will
+/// match the type `target`, otherwise a file symlink is created.
+///
+/// In order to create a symbolic link on Windows, Dart must be run in
+/// Administrator mode or the system must have Developer Mode enabled, otherwise
+/// a [FileSystemException] will be raised with `ERROR_PRIVILEGE_NOT_HELD` set
+/// as the errno when this call is made.
+///
+/// On other platforms, the POSIX `symlink()` call is used to make a symbolic
+/// link containing the string `target`. If `target` is a relative path, it will
+/// be interpreted relative to the directory containing the link.
+///
+/// @description Checks that this method creates the link. Test another [Link]
+/// as a target
+/// @author sgrekhov22@gmail.com
+
+import "dart:io";
+import "../../../Utils/expect.dart";
+import "../file_utils.dart";
+
+main() async {
+  await inSandbox(_main);
+}
+
+_main(Directory sandbox) async {
+  Link target = getTempLinkSync(parent: sandbox);
+  Link link = new Link(getTempFilePath(parent: sandbox));
+  asyncStart();
+  await link.create(target.path).then((Link created) {
+    Expect.isTrue(created.existsSync());
+    Expect.equals(link.path, created.path);
+    Expect.equals(target.path, created.targetSync());
+    asyncEnd();
+  });
+}

LibTest/io/Link/create_A01_t04.dart

@@ -0,0 +1,59 @@
+// Copyright (c) 2023, 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.
+
+/// @assertion Future<Link> create(
+///  String target, {
+///  bool recursive: false
+///  })
+/// Creates a symbolic link in the file system.
+///
+/// The created link will point to the path at `target`, whether that path
+/// exists or not.
+///
+/// Returns a `Future<Link>` that completes with the link when it has been
+/// created. If the link path already exists, the future will complete with an
+/// error.
+///
+/// If `recursive` is `false`, the default, the link is created only if all
+/// directories in its path exist. If `recursive` is `true`, all non-existing
+/// parent paths are created first. The directories in the path of target are
+/// not affected, unless they are also in [path].
+///
+/// On the Windows platform, this call will create a true symbolic link instead
+/// of a junction. The link represents a file or directory and does not change
+/// its type after creation. If `target` exists then the type of the link will
+/// match the type `target`, otherwise a file symlink is created.
+///
+/// In order to create a symbolic link on Windows, Dart must be run in
+/// Administrator mode or the system must have Developer Mode enabled, otherwise
+/// a [FileSystemException] will be raised with `ERROR_PRIVILEGE_NOT_HELD` set
+/// as the errno when this call is made.
+///
+/// On other platforms, the POSIX `symlink()` call is used to make a symbolic
+/// link containing the string `target`. If `target` is a relative path, it will
+/// be interpreted relative to the directory containing the link.
+///
+/// @description Checks that this method creates the link. Test not existing
+/// entity as a target
+/// @author sgrekhov22@gmail.com
+
+import "dart:io";
+import "../../../Utils/expect.dart";
+import "../file_utils.dart";
+
+main() async {
+  await inSandbox(_main);
+}
+
+_main(Directory sandbox) async {
+  String target = getTempFilePath(parent: sandbox);
+  Link link = new Link(getTempFilePath(parent: sandbox));
+  asyncStart();
+  await link.create(target).then((Link created) {
+    Expect.isTrue(created.existsSync());
+    Expect.equals(link.path, created.path);
+    Expect.equals(target, created.targetSync());
+    asyncEnd();
+  });
+}

LibTest/io/Link/create_A02_t01.dart

@@ -6,26 +6,36 @@
 ///  String target, {
 ///  bool recursive: false
 ///  })
-/// Creates a symbolic link. Returns a Future<Link> that completes with the link
-/// when it has been created. If the link exists, the future will complete with
-/// an error.
+/// Creates a symbolic link in the file system.
 ///
-/// If recursive is false, the default, the link is created only if all
-/// directories in its path exist. If recursive is true, all non-existing path
-/// components are created. The directories in the path of target are not
-/// affected, unless they are also in path.
+/// The created link will point to the path at `target`, whether that path
+/// exists or not.
 ///
-/// On the Windows platform, this will only work with directories, and the target
-/// directory must exist. The link will be created as a Junction. Only absolute
-/// links will be created, and relative paths to the target will be converted to
-/// absolute paths by joining them with the path of the directory the link is
-/// contained in.
+/// Returns a `Future<Link>` that completes with the link when it has been
+/// created. If the link path already exists, the future will complete with an
+/// error.
 ///
-/// On other platforms, the posix symlink() call is used to make a symbolic link
-/// containing the string target. If target is a relative path, it will be
-/// interpreted relative to the directory containing the link.
-/// @description Checks that if recursive is false and there are non-existing
-/// path components, then operation fails
+/// If `recursive` is `false`, the default, the link is created only if all
+/// directories in its path exist. If `recursive` is `true`, all non-existing
+/// parent paths are created first. The directories in the path of target are
+/// not affected, unless they are also in [path].
+///
+/// On the Windows platform, this call will create a true symbolic link instead
+/// of a junction. The link represents a file or directory and does not change
+/// its type after creation. If `target` exists then the type of the link will
+/// match the type `target`, otherwise a file symlink is created.
+///
+/// In order to create a symbolic link on Windows, Dart must be run in
+/// Administrator mode or the system must have Developer Mode enabled, otherwise
+/// a [FileSystemException] will be raised with `ERROR_PRIVILEGE_NOT_HELD` set
+/// as the errno when this call is made.
+///
+/// On other platforms, the POSIX `symlink()` call is used to make a symbolic
+/// link containing the string `target`. If `target` is a relative path, it will
+/// be interpreted relative to the directory containing the link.
+///
+/// @description Checks that if `recursive` is `false` and there are
+/// non-existing path components, then operation fails
 /// @author sgrekhov@unipro.ru
 
 import "dart:io";

LibTest/io/Link/create_A02_t02.dart

@@ -6,34 +6,36 @@
 ///  String target, {
 ///  bool recursive: false
 ///  })
-/// Creates a symbolic link. Returns a Future<Link> that completes with the link
-/// when it has been created. If the link exists, the future will complete with
-/// an error.
+/// Creates a symbolic link in the file system.
 ///
-/// If recursive is false, the default, the link is created only if all
-/// directories in its path exist. If recursive is true, all non-existing path
-/// components are created. The directories in the path of target are not
-/// affected, unless they are also in path.
+/// The created link will point to the path at `target`, whether that path
+/// exists or not.
 ///
-/// On the Windows platform, this will only work with directories, and the target
-/// directory must exist. The link will be created as a Junction. Only absolute
-/// links will be created, and relative paths to the target will be converted to
-/// absolute paths by joining them with the path of the directory the link is
-/// contained in.
+/// Returns a `Future<Link>` that completes with the link when it has been
+/// created. If the link path already exists, the future will complete with an
+/// error.
 ///
-/// On other platforms, the posix symlink() call is used to make a symbolic link
-/// containing the string target. If target is a relative path, it will be
-/// interpreted relative to the directory containing the link.
-/// @description Checks that if recursive is true, all non-existing path
-/// components are created
+/// If `recursive` is `false`, the default, the link is created only if all
+/// directories in its path exist. If `recursive` is `true`, all non-existing
+/// parent paths are created first. The directories in the path of target are
+/// not affected, unless they are also in [path].
+///
+/// On the Windows platform, this call will create a true symbolic link instead
+/// of a junction. The link represents a file or directory and does not change
+/// its type after creation. If `target` exists then the type of the link will
+/// match the type `target`, otherwise a file symlink is created.
 ///
-/// @note The test should run with the Administrator priveleges on Windows.
-/// Dart API Spec reads:
 /// In order to create a symbolic link on Windows, Dart must be run in
 /// Administrator mode or the system must have Developer Mode enabled, otherwise
-/// a FileSystemException will be raised with ERROR_PRIVILEGE_NOT_HELD set as
-/// the errno when this call is made.
+/// a [FileSystemException] will be raised with `ERROR_PRIVILEGE_NOT_HELD` set
+/// as the errno when this call is made.
 ///
+/// On other platforms, the POSIX `symlink()` call is used to make a symbolic
+/// link containing the string `target`. If `target` is a relative path, it will
+/// be interpreted relative to the directory containing the link.
+///
+/// @description Checks that if `recursive` is `true`, all non-existing path
+/// components are created
 /// @author sgrekhov@unipro.ru
 
 import "dart:io";