From 39bafed1021a49d7fd7458a34989601a8493f79a Mon Sep 17 00:00:00 2001
From: Ian Lance Taylor <iant@golang.org>
Date: Tue, 30 May 2023 10:42:57 -0700
Subject: [PATCH] doc/go1.21: document io/fs formatting functions

Also document the new String methods that call them.

For #54451

Change-Id: I5cd7e0fc6c84097bba6d29c4d6012ed3c8bb1e0d
Reviewed-on: https://go-review.googlesource.com/c/go/+/499177
Reviewed-by: Eli Bendersky <eliben@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
TryBot-Bypass: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
---
 doc/go1.21.html | 109 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 99 insertions(+), 10 deletions(-)

diff --git a/doc/go1.21.html b/doc/go1.21.html
index 31157b02519000..d0fd953ba12db9 100644
--- a/doc/go1.21.html
+++ b/doc/go1.21.html
@@ -292,6 +292,45 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
   TODO: complete this section
 </p>
 
+<dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>
+  <dd>
+    <p><!-- https://go.dev/issue/54451, CL 491175 -->
+      The implementation of the
+      <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
+      interface returned by
+      <a href="/pkg/archive/tar/#Header.FileInfo"><code>Header.FileInfo</code></a>
+      now implements a <code>String</code> method that calls
+      <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
+    </p>
+  </dd>
+</dl><!-- archive/tar -->
+
+<dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
+  <dd>
+    <p><!-- https://go.dev/issue/54451, CL 491175 -->
+      The implementation of the
+      <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
+      interface returned by
+      <a href="/pkg/archive/zip/#FileHeader.FileInfo"><code>FileHeader.FileInfo</code></a>
+      now implements a <code>String</code> method that calls
+      <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
+    </p>
+
+    <p><!-- https://go.dev/issue/54451, CL 491175 -->
+      The implementation of the
+      <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
+      interface returned by the
+      <a href="/pkg/io/fs/#ReadDirFile.ReadDir"><code>io/fs.ReadDirFile.ReadDir</code></a>
+      method of the
+      <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
+      returned by
+      <a href="/pkg/archive/zip/#Reader.Open"><code>Reader.Open</code></a>
+      now implements a <code>String</code> method that calls
+      <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
+    </p>
+  </dd>
+</dl><!-- archive/zip -->
+
 <dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
   <dd>
     <p><!-- https://go.dev/issue/53685 -->
@@ -430,6 +469,13 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
     <p><!-- CL 483235 -->
       TODO: <a href="https://go.dev/cl/483235">https://go.dev/cl/483235</a>: embed: implement openFile.ReadAt
     </p>
+
+    <p><!-- https://go.dev/issue/54451, CL 491175 -->
+      Calling <code><a href="/pkg/embed/FS.Open">FS.Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
+      will return a type that now implements a <code>String</code>
+      method that calls
+      <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
+    </p>
   </dd>
 </dl><!-- embed -->
 
@@ -465,14 +511,6 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
   </dd>
 </dl><!-- flag -->
 
-<dl id="fs"><dt><a href="/pkg/fs/">fs</a></dt>
-  <dd>
-    <p><!-- https://go.dev/issue/54451 -->
-      TODO: <a href="https://go.dev/issue/54451">https://go.dev/issue/54451</a>: standard implementations of FileInfo and DirEntry should implement fmt.Stringer
-    </p>
-  </dd>
-</dl><!-- fs -->
-
 <dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
   <dd>
     <p><!-- https://go.dev/issue/28089, CL 487935 -->
@@ -541,8 +579,25 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
 
 <dl id="io/fs"><dt><a href="/pkg/io/fs/">io/fs</a></dt>
   <dd>
-    <p><!-- CL 489555 -->
-      TODO: <a href="https://go.dev/cl/489555">https://go.dev/cl/489555</a>: io/fs: add FormatFileInfo and FormatDirEntry functions; modified api/next/54451.txt
+    <p><!-- https://go.dev/issue/54451, CL 489555 -->
+      The new
+      <a href="/pkg/io/fs/#FormatFileInfo"><code>FormatFileInfo</code></a>
+      function returns a formatted version of a
+      <a href="/pkg/io/fs/#FileInfo"><code>FileInfo</code></a>.
+      The new
+      <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>
+      function returns a formatted version of a
+      <a href="/pkg/io/fs/#FileInfo"><code>DirEntry</code></a>.
+      The implementation of
+      <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
+      returned by
+      <a href="/pkg/io/fs/#ReadDir"><code>ReadDir</code></a> now
+      implements a <code>String</code> method that calls
+      <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>,
+      and the same is true for
+      the <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
+      value passed to
+      <a href="/pkg/io/fs/#WalkDirFunc"><code>WalkDirFunc</code></a>.
     </p>
   </dd>
 </dl><!-- io/fs -->
@@ -705,9 +760,32 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
       On Windows the os package now supports working with files whose
       names, stored as UTF-16, can't be represented as valid UTF-8.
     </p>
+
+    <p><!-- https://go.dev/issue/54451, CL 491175 -->
+      The implementation of the
+      <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
+      interface returned by the
+      <a href="/pkg/os/#ReadDir"><code>ReadDir</code></a> function and
+      the <a href="/pkg/os/#File.ReadDir"><code>File.ReadDir</code>
+      method now implements a <code>String</code> method that calls
+      <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
+    </p>
   </dd>
 </dl><!-- os -->
 
+<dl id="path/filepath"><dt><a href="/pkg/path/filepath/">path/filepath</a></dt>
+  <dd>
+    <p>
+      The implementation of the
+      <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
+      interface passed to the function argument of
+      <a href="/pkg/path/filepath/#WalkDir"><code>WalkDir</code></a>
+      now implements a <code>String</code> method that calls
+      <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
+    </p>
+  </dd>
+</dl><!-- path/filepath -->
+
 <!-- CL 459455 reverted -->
 
 <dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
@@ -888,6 +966,17 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
   </dd>
 </dl><!-- testing -->
 
+<dl id="testing/fstest"><dt><a href="/pkg/testing/fstest/">testing/fstest</a></dt>
+  <dd>
+    <p><!-- https://go.dev/issue/54451, CL 491175 -->
+      Calling <code><a href="/pkg/testing/fstest/MapFS.Open">Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
+      will return a type that now implements a <code>String</code>
+      method that calls
+      <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
+    </p>
+  </dd>
+</dl><!-- testing/fstest -->
+
 <dl id="testing/slogtest"><dt><a href="/pkg/testing/slogtest/">testing/slogtest</a></dt>
   <dd>
     <p><!-- CL 487895 -->