Improve docs for createTempDir/createTempFile

#KT-35218

libraries/stdlib/jvm/src/kotlin/io/files/Utils.kt

@@ -14,10 +14,15 @@ import java.io.IOException
 /**
  * Creates an empty directory in the specified [directory], using the given [prefix] and [suffix] to generate its name.
  *
- * If [prefix] is not specified then some unspecified name will be used.
+ * If [prefix] is not specified then some unspecified string will be used.
  * If [suffix] is not specified then ".tmp" will be used.
  * If [directory] is not specified then the default temporary-file directory will be used.
  *
+ * The [prefix] argument, if specified, must be at least three characters long.
+ * It is recommended that the prefix be a short, meaningful string such as "job" or "mail".
+ *
+ * To create the new file, the [prefix] and the [suffix] may first be adjusted to fit the limitations of the underlying platform.
+ *
  * @return a file object corresponding to a newly-created directory.
  *
  * @throws IOException in case of input/output error.
@@ -36,10 +41,15 @@ public fun createTempDir(prefix: String = "tmp", suffix: String? = null, directo
 /**
  * Creates a new empty file in the specified [directory], using the given [prefix] and [suffix] to generate its name.
  *
- * If [prefix] is not specified then some unspecified name will be used.
+ * If [prefix] is not specified then some unspecified string will be used.
  * If [suffix] is not specified then ".tmp" will be used.
  * If [directory] is not specified then the default temporary-file directory will be used.
  *
+ * The [prefix] argument, if specified, must be at least three characters long.
+ * It is recommended that the prefix be a short, meaningful string such as "job" or "mail".
+ *
+ * To create the new file, the [prefix] and the [suffix] may first be adjusted to fit the limitations of the underlying platform.
+ *
  * @return a file object corresponding to a newly-created file.
  *
  * @throws IOException in case of input/output error.

libraries/stdlib/jvm/test/io/Files.kt

@@ -32,10 +32,10 @@ class FilesTest {
         }
 
         val dir2 = createTempDir("temp")
-        assertTrue(dir2.exists() && dir2.isDirectory && dir2.name.endsWith(".tmp"))
+        assertTrue(dir2.exists() && dir2.isDirectory && dir2.name.startsWith("temp") && dir2.name.endsWith(".tmp"))
 
         val dir3 = createTempDir()
-        assertTrue(dir3.exists() && dir3.isDirectory)
+        assertTrue(dir3.exists() && dir3.isDirectory && dir3.name.startsWith("tmp") && dir3.name.endsWith(".tmp"))
 
         dir1.delete()
         dir2.delete()
@@ -51,10 +51,10 @@ class FilesTest {
         }
 
         val file2 = createTempFile("temp")
-        assertTrue(file2.exists() && file2.name.endsWith(".tmp"))
+        assertTrue(file2.exists() && file2.name.startsWith("temp") && file2.name.endsWith(".tmp"))
 
         val file3 = createTempFile()
-        assertTrue(file3.exists())
+        assertTrue(file3.exists() && file3.name.startsWith("tmp") && file3.name.endsWith(".tmp"))
 
         file1.delete()
         file2.delete()