emacsWithPackages: add user documentation

1 files changed, 34 insertions, 0 deletions

diff --git a/pkgs/build-support/emacs/wrapper.nix b/pkgs/build-support/emacs/wrapper.nix
index 8de13dc0c64..dc4ff03f9e7 100644
--- a/pkgs/build-support/emacs/wrapper.nix
+++ b/pkgs/build-support/emacs/wrapper.nix
@@ -1,3 +1,37 @@
+/*
+
+# Usage
+
+`emacsWithPackages` takes a single argument: a function from a package
+set to a list of packages (the packages that will be available in
+Emacs). For example,
+```
+emacsWithPackages (epkgs: [ epkgs.evil epkgs.magit ])
+```
+All the packages in the list should come from the provided package
+set. It is possible to add any package to the list, but the provided
+set is guaranteed to have consistent dependencies and be built with
+the correct version of Emacs.
+
+# Overriding
+
+`emacsWithPackages` inherits the package set which contains it, so the
+correct way to override the provided package set is to override the
+set which contains `emacsWithPackages`. For example, to override
+`emacsPackagesNg.emacsWithPackages`,
+```
+let customEmacsPackages =
+      emacsPackagesNg.override (super: self: {
+        # use a custom version of emacs
+        emacs = ...;
+        # use the unstable MELPA version of magit
+        magit = self.melpaPackages.magit;
+      });
+in customEmacsPackages.emacsWithPackages (epkgs: [ epkgs.evil epkgs.magit ])
+```
+
+*/
+
 { lib, makeWrapper, stdenv }: self:
 
 with lib; let inherit (self) emacs; in