From 257557be073e697c61e70005d32642ac9515451b Mon Sep 17 00:00:00 2001
From: Steve Purcell <steve@sanityinc.com>
Date: Sat, 20 Jun 2020 15:59:29 +1200
Subject: Add docstring with example Package-Requires parse inputs and results

---
 parse.nix | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/parse.nix b/parse.nix
index 6244b6954fbe..3fc18b7f0a46 100644
--- a/parse.nix
+++ b/parse.nix
@@ -6,6 +6,19 @@ let
     (x: builtins.typeOf x == "string")
     (builtins.split _sep _s);
 
+  # Parse (all) Package-Requires elisp headers found in the input string
+  # `packageFile` into a list of package name strings.
+  #
+  # Example inputs:
+  #
+  #  ;; Package-Requires: ()
+  #  => [ ]
+  #  ;; Package-Requires: ((dash "2.12.1") (pkg-info "0.4") (let-alist "1.0.4") (seq "1.11") (emacs "24.3"))
+  #  => [ "dash" "pkg-info" "let-alist" "seq" "emacs" ]
+  #  ;; Package-Requires: (dash (pkg-info "0.4"))
+  #  => [ "dash" "pkg-info" ]
+  #  ;; Package-Requires: ((dash) (pkg-info "0.4"))
+  #  => [ "dash" "pkg-info" ]
   parsePackagesFromPackageRequires = packageFile:
     let
       lines = splitString "\r?\n" packageFile;
-- 
cgit 1.4.1