# HG changeset patch
# User Augie Fackler <augie@google.com>
# Date 2017-05-20 21:58:04
# Node ID 1f4be037f558249b89805124d048e8a6af544798
# Parent  7d8da7b54dc09b5686915fc6c9c1ee33fe910c36

cmdutil: comprehensively document the interface of export

I want to make some improvements here, but in order to make future
patches easier to review I want to document the current state of the
world.

diff --git a/mercurial/cmdutil.py b/mercurial/cmdutil.py
--- a/mercurial/cmdutil.py
+++ b/mercurial/cmdutil.py
@@ -1143,7 +1143,30 @@ extraexportmap = {}
 
 def export(repo, revs, template='hg-%h.patch', fp=None, switch_parent=False,
            opts=None, match=None):
-    '''export changesets as hg patches.'''
+    '''export changesets as hg patches
+
+    Args:
+      repo: The repository from which we're exporting revisions.
+      revs: A list of revisions to export as revision numbers.
+      template: An optional string to use for generating patch file names.
+      fp: An optional file-like object to which patches should be written.
+      switch_parent: If True, show diffs against second parent when not nullid.
+                     Default is false, which always shows diff against p1.
+      opts: diff options to use for generating the patch.
+      match: If specified, only export changes to files matching this matcher.
+
+    Returns:
+      Nothing.
+
+    Side Effect:
+      "HG Changeset Patch" data is emitted to one of the following
+      destinations:
+        fp is specified: All revs are written to the specified
+                         file-like object.
+        template specified: Each rev is written to a unique file named using
+                            the given template.
+        Neither fp nor template specified: All revs written to repo.ui.write()
+    '''
 
     total = len(revs)
     revwidth = max([len(str(rev)) for rev in revs])