docs(wpcarro/emacs): Document list.el r/4386

- Add README.md
- Remove stale TODOs
- Rephrase some of the module docs

Change-Id: I14002836feeca4dd702350151b64600ea2a9125d
Reviewed-on: https://cl.tvl.fyi/c/depot/+/6042
Reviewed-by: wpcarro <wpcarro@gmail.com>
Autosubmit: wpcarro <wpcarro@gmail.com>
Tested-by: BuildkiteCI

2 files changed, 25 insertions, 32 deletions

diff --git a/users/wpcarro/emacs/pkgs/list/README.md b/users/wpcarro/emacs/pkgs/list/README.md
new file mode 100644
index 000000000000..7afa8494fb7a
--- /dev/null
+++ b/users/wpcarro/emacs/pkgs/list/README.md
@@ -0,0 +1,19 @@
+# list.el
+
+Functions for working with lists in Elisp.
+
+## Wish List
+
+Here are some additional functions that I'd like to support.
+
+-  **TODO**: delete_at/2
+-  **TODO**: flatten/1
+-  **TODO**: flatten/2
+-  **TODO**: foldl/3
+-  **TODO**: foldr/3
+-  **TODO**: insert_at/3
+-  **TODO**: pop_at/3
+-  **TODO**: replace_at/3
+-  **TODO**: starts_with?/2
+-  **TODO**: update_at/3
+-  **TODO**: zip/1
diff --git a/users/wpcarro/emacs/pkgs/list/list.el b/users/wpcarro/emacs/pkgs/list/list.el
index a395eba2672e..3196d85856c1 100644
--- a/users/wpcarro/emacs/pkgs/list/list.el
+++ b/users/wpcarro/emacs/pkgs/list/list.el
@@ -6,45 +6,23 @@
 
 ;;; Commentary:
 ;; Since I prefer having the `list-' namespace, I wrote this module to wrap many
-;; of the functions that are defined in the the global namespace in ELisp.  I
+;; of the functions that are defined in the the global namespace in Elisp.  I
 ;; sometimes forget the names of these functions, so it's nice for them to be
 ;; organized like this.
 ;;
 ;; Motivation:
-;; Here are some examples of function names that I cannot tolerate:
+;; Here are some examples of function names where I prefer more modern
+;; alternatives:
 ;; - `car': Return the first element (i.e. "head") of a linked list
 ;; - `cdr': Return the tail of a linked list
 
-;; As are most APIs for standard libraries that I write, this is heavily
-;; influenced by Elixir's standard library.
-;;
-;; Elixir's List library:
-;; - ++/2
-;; - --/2
-;; - hd/1
-;; - tl/1
-;; - in/2
-;; - length/1
+;; As are most APIs for standard libraries that I write, this is influenced by
+;; Elixir's standard library.
 ;;
 ;; Similar libraries:
-;; - dash.el: Functional library that mimmicks Clojure.  It is consumed herein.
+;; - dash.el: Excellent and widely adopted library for working with lists.
 ;; - list-utils.el: Utility library that covers things that dash.el may not
 ;;   cover.
-;;   stream.el: Elisp implementation of streams, "implemented as delayed
-;;   evaluation of cons cells."
-
-;; TODO: Consider naming this file linked-list.el.
-
-;; TODO: Support module-like macro that auto-namespaces functions.
-
-;; TODO: Consider wrapping most data structures like linked-lists,
-;; associative-lists, etc in a `cl-defstruct', so that the dispatching by type
-;; can be nominal instead of duck-typing.  I'm not sure if this is a good idea
-;; or not.  If I do this, I should provide isomorphisms to map between idiomatic
-;; ways of working with Elisp data structures and my wrapped variants.
-
-;; TODO: Are function aliases/synonyms even a good idea?  Or do they just
-;; bloat the API unnecessarily?
 
 ;;; Code:
 
@@ -159,10 +137,6 @@ Returns a new list without X. If X occurs more than once, only the first
   (list--assert-instance xs)
   (seq-find p xs))
 
-;; TODO: Support dedupe.
-;; TODO: Should we call this unique? Or distinct?
-
-;; TODO: Add tests.
 (defun list-dedupe-adjacent (xs)
   "Return XS without adjacent duplicates."
   (list-reverse