From f45d2569408d90699a278f4cb2a02ffab4db8fa3 Mon Sep 17 00:00:00 2001
From: Nate Fischer <ntfschr@google.com>
Date: Sat, 15 Jan 2022 12:29:57 -0800
Subject: [PATCH] docs(ls): document the toString() override

No change to logic. This documents `shell.ls('-l')`'s `.toString()`
override. I noticed this feature was not documented. This string format
should not be depended on by programmatic usage, but it's useful to make
things more human readable.
---
 README.md | 12 ++++++++----
 src/ls.js | 12 ++++++++----
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 05076e6..6b09426 100644
--- a/README.md
+++ b/README.md
@@ -430,10 +430,14 @@ Available options:
 + `-A`: all files (include files beginning with `.`, except for `.` and `..`)
 + `-L`: follow symlinks
 + `-d`: list directories themselves, not their contents
-+ `-l`: list objects representing each file, each with fields containing `ls
-        -l` output fields. See
-        [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)
-        for more info
++ `-l`: provides more details for each file. Specifically, each file is
+        represented by a structured object with separate fields for file
+        metadata (see
+        [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)). The
+        return value also overrides `.toString()` to resemble `ls -l`'s
+        output format for human readability, but programmatic usage should
+        depend on the stable object format rather than the `.toString()`
+        representation.
 
 Examples:
 
diff --git a/src/ls.js b/src/ls.js
index d2b2e0b..4faa30b 100644
--- a/src/ls.js
+++ b/src/ls.js
@@ -26,10 +26,14 @@ common.register('ls', _ls, {
 //@ + `-A`: all files (include files beginning with `.`, except for `.` and `..`)
 //@ + `-L`: follow symlinks
 //@ + `-d`: list directories themselves, not their contents
-//@ + `-l`: list objects representing each file, each with fields containing `ls
-//@         -l` output fields. See
-//@         [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)
-//@         for more info
+//@ + `-l`: provides more details for each file. Specifically, each file is
+//@         represented by a structured object with separate fields for file
+//@         metadata (see
+//@         [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)). The
+//@         return value also overrides `.toString()` to resemble `ls -l`'s
+//@         output format for human readability, but programmatic usage should
+//@         depend on the stable object format rather than the `.toString()`
+//@         representation.
 //@
 //@ Examples:
 //@