From 2f76fd5cc241b520406cbbb225afe7b0f9c3af43 Mon Sep 17 00:00:00 2001
From: Tom Ritchford <tom@swirly.com>
Date: Sat, 6 Jan 2024 12:22:34 +0100
Subject: [PATCH] Improve documentation

---
 README.md          | 17 +++++++++--------
 editor/__init__.py | 17 +++++++++--------
 2 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 1dfe217..8f2aca8 100644
--- a/README.md
+++ b/README.md
@@ -17,27 +17,28 @@ case the editor is:
 If no filename is provided, a temporary file gets edited, and its contents
 returned.
 
-    from editor import editor
+    import editor
 
-    MESSAGE = 'Insert comments below this line\n\n'
-    comments = editor(text=MESSAGE)
-    # Pops up the default editor with a tempfile, containing MESSAGE
+    comments = editor.editor(text='Comments here\n\n')
+    # Pop up the default editor with a tempfile containing "Comments here",
+    # then return the contents and delete the tempfile.
 
 ### Example 2: Using a named file
 
-If a filename is provided, then it gets edited!
+If a filename is provided, then that file gets edited.
 
     import os
 
     FILE = 'file.txt'
     assert not os.path.exists(FILE)
 
-    comments = editor(text=MESSAGE, filename=FILE)
-    # Pops up an editor for new FILE containing MESSAGE, user edits
+    comments = editor.editor(text=MESSAGE, filename=FILE)
+    # Pop up an editor for a new FILE containing MESSAGE, user edits
+    # This file is saved when the user exits the editor.
 
     assert os.path.exists(FILE)
 
     # You can edit an existing file too, and select your own editor.
-    comments2 = editor(filename=FILE, editor='emacs -nw')
+    comments2 = editor.editor(filename=FILE, editor='emacs -nw')
 
 ### [API Documentation](https://rec.github.io/editor#editor--api-documentation)
diff --git a/editor/__init__.py b/editor/__init__.py
index 4865b0f..04d2619 100644
--- a/editor/__init__.py
+++ b/editor/__init__.py
@@ -18,28 +18,29 @@
 If no filename is provided, a temporary file gets edited, and its contents
 returned.
 
-    from editor import editor
+    import editor
 
-    MESSAGE = 'Insert comments below this line\\n\\n'
-    comments = editor(text=MESSAGE)
-    # Pops up the default editor with a tempfile, containing MESSAGE
+    comments = editor.editor(text='Comments here\\n\\n')
+    # Pop up the default editor with a tempfile containing "Comments here",
+    # then return the contents and delete the tempfile.
 
 ### Example 2: Using a named file
 
-If a filename is provided, then it gets edited!
+If a filename is provided, then that file gets edited.
 
     import os
 
     FILE = 'file.txt'
     assert not os.path.exists(FILE)
 
-    comments = editor(text=MESSAGE, filename=FILE)
-    # Pops up an editor for new FILE containing MESSAGE, user edits
+    comments = editor.editor(text=MESSAGE, filename=FILE)
+    # Pop up an editor for a new FILE containing MESSAGE, user edits
+    # This file is saved when the user exits the editor.
 
     assert os.path.exists(FILE)
 
     # You can edit an existing file too, and select your own editor.
-    comments2 = editor(filename=FILE, editor='emacs -nw')
+    comments2 = editor.editor(filename=FILE, editor='emacs -nw')
 """
 
 import os