dart-lang#2291. Update Link.createSync() according to the new docum…

…entation. Part 1

LibTest/io/Link/createSync_A01_t01.dart

@@ -3,34 +3,33 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /// @assertion void createSync(
-///  String target, {
-///  bool recursive: false
-///  })
+/// String target,
+/// {bool recursive = false}
+/// )
 ///  Synchronously create the link. Calling createSync on an existing link will
 ///  throw an exception.
 ///
-///  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.
+/// 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 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.
+/// 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.
 ///
-///  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
-///
-/// @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.
+/// 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 [Directory] as a
+/// target
 /// @author sgrekhov@unipro.ru
 
 import "dart:io";

LibTest/io/Link/createSync_A01_t02.dart

@@ -0,0 +1,49 @@
+// 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 void createSync(
+/// String target,
+/// {bool recursive = false}
+/// )
+///  Synchronously create the link. Calling createSync on an existing link will
+///  throw an exception.
+///
+/// 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));
+  link.createSync(target.path);
+  Expect.isTrue(link.existsSync());
+  Expect.equals(target.path, link.targetSync());
+}

LibTest/io/Link/createSync_A01_t03.dart

@@ -0,0 +1,49 @@
+// 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 void createSync(
+/// String target,
+/// {bool recursive = false}
+/// )
+///  Synchronously create the link. Calling createSync on an existing link will
+///  throw an exception.
+///
+/// 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, target: sandbox.path);
+  Link link = new Link(getTempFilePath(parent: sandbox));
+  link.createSync(target.path);
+  Expect.isTrue(link.existsSync());
+  Expect.equals(target.path, link.targetSync());
+}

LibTest/io/Link/createSync_A01_t04.dart

@@ -0,0 +1,49 @@
+// 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 void createSync(
+/// String target,
+/// {bool recursive = false}
+/// )
+///  Synchronously create the link. Calling createSync on an existing link will
+///  throw an exception.
+///
+/// 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));
+  link.createSync(target);
+  Expect.isTrue(link.existsSync());
+  Expect.equals(target, link.targetSync());
+}

LibTest/io/Link/createSync_A02_t01.dart

@@ -3,27 +3,33 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /// @assertion void createSync(
-///  String target, {
-///  bool recursive: false
-///  })
+/// String target,
+/// {bool recursive = false}
+/// )
 ///  Synchronously create the link. Calling createSync on an existing link will
 ///  throw an exception.
 ///
-///  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.
+/// 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 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.
+/// 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.
 ///
-///  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
+/// 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/createSync_A02_t02.dart

@@ -3,35 +3,33 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /// @assertion void createSync(
-///  String target, {
-///  bool recursive: false
-///  })
+/// String target,
+/// {bool recursive = false}
+/// )
 ///  Synchronously create the link. Calling createSync on an existing link will
 ///  throw an exception.
 ///
-///  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.
+/// 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 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.
+/// 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.
 ///
-///  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
-///
-/// @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.
+/// 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 `true`, all non-existing path
+/// components are created
 /// @author sgrekhov@unipro.ru
 
 import "dart:io";

LibTest/io/Link/createSync_A02_t03.dart

@@ -3,35 +3,33 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /// @assertion void createSync(
-///  String target, {
-///  bool recursive: false
-///  })
+/// String target,
+/// {bool recursive = false}
+/// )
 ///  Synchronously create the link. Calling createSync on an existing link will
 ///  throw an exception.
 ///
-///  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.
+/// 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 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.
+/// 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.
 ///
-///  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 the directories in the path of
-/// target are not affected
-///
-/// @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.
+/// 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 true the directories in the path of
+/// target are not affected
 /// @author sgrekhov@unipro.ru
 
 import "dart:io";
@@ -44,7 +42,6 @@ main() async {
 
 _main(Directory sandbox) async {
   String dirPath = getTempDirectoryPath(parent: sandbox);
-  Directory dir = new Directory(dirPath);
   String targetPath = getTempDirectoryPath(parent: sandbox);
   Directory target = new Directory(targetPath);
   String linkPath =