changeset 6666:53465a7464e2

convert comments to docstrings in a bunch of extensions

--- a/hgext/churn.py	Thu Jun 12 13:12:09 2008 +0200
+++ b/hgext/churn.py	Thu Jun 12 11:33:47 2008 +0200
@@ -4,12 +4,7 @@
 #
 # This software may be used and distributed according to the terms
 # of the GNU General Public License, incorporated herein by reference.
-#
-#
-# Aliases map file format is simple one alias per line in the following
-# format:
-#
-# <alias email> <actual email>
+'''allow graphing the number of lines changed per contributor'''
 
 from mercurial.i18n import gettext as _
 from mercurial import mdiff, cmdutil, util, node
@@ -137,7 +132,11 @@
     return stats
 
 def churn(ui, repo, **opts):
-    "Graphs the number of lines changed"
+    '''graphs the number of lines changed
+
+    The map file format used to specify aliases is fairly simple:
+
+    <alias email> <actual email>'''
 
     def pad(s, l):
         if len(s) < l:

--- a/hgext/convert/__init__.py	Thu Jun 12 13:12:09 2008 +0200
+++ b/hgext/convert/__init__.py	Thu Jun 12 11:33:47 2008 +0200
@@ -4,6 +4,7 @@
 #
 # This software may be used and distributed according to the terms
 # of the GNU General Public License, incorporated herein by reference.
+'''converting foreign VCS repositories to Mercurial'''
 
 import convcmd
 from mercurial import commands

--- a/hgext/fetch.py	Thu Jun 12 13:12:09 2008 +0200
+++ b/hgext/fetch.py	Thu Jun 12 11:33:47 2008 +0200
@@ -4,6 +4,7 @@
 #
 # This software may be used and distributed according to the terms
 # of the GNU General Public License, incorporated herein by reference.
+'''pulling, updating and merging in one command'''
 
 from mercurial.i18n import _
 from mercurial.node import nullid, short

--- a/hgext/graphlog.py	Thu Jun 12 13:12:09 2008 +0200
+++ b/hgext/graphlog.py	Thu Jun 12 11:33:47 2008 +0200
@@ -4,6 +4,7 @@
 #
 # This software may be used and distributed according to the terms of
 # the GNU General Public License, incorporated herein by reference.
+'''show revision graphs in terminal windows'''
 
 import os
 import sys

--- a/hgext/hgk.py	Thu Jun 12 13:12:09 2008 +0200
+++ b/hgext/hgk.py	Thu Jun 12 11:33:47 2008 +0200
@@ -4,46 +4,45 @@
 #
 # This software may be used and distributed according to the terms
 # of the GNU General Public License, incorporated herein by reference.
-#
-# The hgk extension allows browsing the history of a repository in a
-# graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is
-# not distributed with Mercurial.)
-#
-# hgk consists of two parts: a Tcl script that does the displaying and
-# querying of information, and an extension to mercurial named hgk.py,
-# which provides hooks for hgk to get information. hgk can be found in
-# the contrib directory, and hgk.py can be found in the hgext
-# directory.
-#
-# To load the hgext.py extension, add it to your .hgrc file (you have
-# to use your global $HOME/.hgrc file, not one in a repository). You
-# can specify an absolute path:
-#
-#   [extensions]
-#   hgk=/usr/local/lib/hgk.py
-#
-# Mercurial can also scan the default python library path for a file
-# named 'hgk.py' if you set hgk empty:
-#
-#   [extensions]
-#   hgk=
-#
-# The hg view command will launch the hgk Tcl script. For this command
-# to work, hgk must be in your search path. Alternately, you can
-# specify the path to hgk in your .hgrc file:
-#
-#   [hgk]
-#   path=/location/of/hgk
-#
-# hgk can make use of the extdiff extension to visualize
-# revisions. Assuming you had already configured extdiff vdiff
-# command, just add:
-#
-#   [hgk]
-#   vdiff=vdiff
-#
-# Revisions context menu will now display additional entries to fire
-# vdiff on hovered and selected revisions.
+'''browsing the repository in a graphical way
+
+The hgk extension allows browsing the history of a repository in a
+graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is
+not distributed with Mercurial.)
+
+hgk consists of two parts: a Tcl script that does the displaying and
+querying of information, and an extension to mercurial named hgk.py,
+which provides hooks for hgk to get information. hgk can be found in
+the contrib directory, and hgk.py can be found in the hgext directory.
+
+To load the hgext.py extension, add it to your .hgrc file (you have
+to use your global $HOME/.hgrc file, not one in a repository). You
+can specify an absolute path:
+
+  [extensions]
+  hgk=/usr/local/lib/hgk.py
+
+Mercurial can also scan the default python library path for a file
+named 'hgk.py' if you set hgk empty:
+
+  [extensions]
+  hgk=
+
+The hg view command will launch the hgk Tcl script. For this command
+to work, hgk must be in your search path. Alternately, you can
+specify the path to hgk in your .hgrc file:
+
+  [hgk]
+  path=/location/of/hgk
+
+hgk can make use of the extdiff extension to visualize revisions.
+Assuming you had already configured extdiff vdiff command, just add:
+
+  [hgk]
+  vdiff=vdiff
+
+Revisions context menu will now display additional entries to fire
+vdiff on hovered and selected revisions.'''
 
 import os
 from mercurial import commands, util, patch, revlog, cmdutil

--- a/hgext/highlight.py	Thu Jun 12 13:12:09 2008 +0200
+++ b/hgext/highlight.py	Thu Jun 12 11:33:47 2008 +0200
@@ -1,6 +1,4 @@
-"""
-This is Mercurial extension for syntax highlighting in the file
-revision view of hgweb.
+"""a mercurial extension for syntax highlighting in hgweb
 
 It depends on the pygments syntax highlighting library:
 http://pygments.org/

--- a/hgext/patchbomb.py	Thu Jun 12 13:12:09 2008 +0200
+++ b/hgext/patchbomb.py	Thu Jun 12 11:33:47 2008 +0200
@@ -1,68 +1,65 @@
-# Command for sending a collection of Mercurial changesets as a series
-# of patch emails.
-#
-# The series is started off with a "[PATCH 0 of N]" introduction,
-# which describes the series as a whole.
-#
-# Each patch email has a Subject line of "[PATCH M of N] ...", using
-# the first line of the changeset description as the subject text.
-# The message contains two or three body parts:
-#
-#   The remainder of the changeset description.
-#
-#   [Optional] If the diffstat program is installed, the result of
-#   running diffstat on the patch.
-#
-#   The patch itself, as generated by "hg export".
-#
-# Each message refers to all of its predecessors using the In-Reply-To
-# and References headers, so they will show up as a sequence in
-# threaded mail and news readers, and in mail archives.
-#
-# For each changeset, you will be prompted with a diffstat summary and
-# the changeset summary, so you can be sure you are sending the right
-# changes.
-#
-# To enable this extension:
-#
-#   [extensions]
-#   hgext.patchbomb =
-#
-# To configure other defaults, add a section like this to your hgrc
-# file:
-#
-#   [email]
-#   from = My Name <my@email>
-#   to = recipient1, recipient2, ...
-#   cc = cc1, cc2, ...
-#   bcc = bcc1, bcc2, ...
-#
-# Then you can use the "hg email" command to mail a series of changesets
-# as a patchbomb.
-#
-# To avoid sending patches prematurely, it is a good idea to first run
-# the "email" command with the "-n" option (test only).  You will be
-# prompted for an email recipient address, a subject an an introductory
-# message describing the patches of your patchbomb.  Then when all is
-# done, patchbomb messages are displayed. If PAGER environment variable
-# is set, your pager will be fired up once for each patchbomb message, so
-# you can verify everything is alright.
-#
-# The "-m" (mbox) option is also very useful.  Instead of previewing
-# each patchbomb message in a pager or sending the messages directly,
-# it will create a UNIX mailbox file with the patch emails.  This
-# mailbox file can be previewed with any mail user agent which supports
-# UNIX mbox files, i.e. with mutt:
-#
-#   % mutt -R -f mbox
-#
-# When you are previewing the patchbomb messages, you can use `formail'
-# (a utility that is commonly installed as part of the procmail package),
-# to send each message out:
-#
-#  % formail -s sendmail -bm -t < mbox
-#
-# That should be all.  Now your patchbomb is on its way out.
+'''sending Mercurial changesets as a series of patch emails
+
+The series is started off with a "[PATCH 0 of N]" introduction,
+which describes the series as a whole.
+
+Each patch email has a Subject line of "[PATCH M of N] ...", using
+the first line of the changeset description as the subject text.
+The message contains two or three body parts:
+
+  The remainder of the changeset description.
+
+  [Optional] If the diffstat program is installed, the result of
+  running diffstat on the patch.
+
+  The patch itself, as generated by "hg export".
+
+Each message refers to all of its predecessors using the In-Reply-To
+and References headers, so they will show up as a sequence in
+threaded mail and news readers, and in mail archives.
+
+For each changeset, you will be prompted with a diffstat summary and
+the changeset summary, so you can be sure you are sending the right changes.
+
+To enable this extension:
+
+  [extensions]
+  hgext.patchbomb =
+
+To configure other defaults, add a section like this to your hgrc file:
+
+  [email]
+  from = My Name <my@email>
+  to = recipient1, recipient2, ...
+  cc = cc1, cc2, ...
+  bcc = bcc1, bcc2, ...
+
+Then you can use the "hg email" command to mail a series of changesets
+as a patchbomb.
+
+To avoid sending patches prematurely, it is a good idea to first run
+the "email" command with the "-n" option (test only).  You will be
+prompted for an email recipient address, a subject an an introductory
+message describing the patches of your patchbomb.  Then when all is
+done, patchbomb messages are displayed. If PAGER environment variable
+is set, your pager will be fired up once for each patchbomb message, so
+you can verify everything is alright.
+
+The "-m" (mbox) option is also very useful.  Instead of previewing
+each patchbomb message in a pager or sending the messages directly,
+it will create a UNIX mailbox file with the patch emails.  This
+mailbox file can be previewed with any mail user agent which supports
+UNIX mbox files, i.e. with mutt:
+
+  % mutt -R -f mbox
+
+When you are previewing the patchbomb messages, you can use `formail'
+(a utility that is commonly installed as part of the procmail package),
+to send each message out:
+
+  % formail -s sendmail -bm -t < mbox
+
+That should be all. Now your patchbomb is on its way out.'''
 
 import os, errno, socket, tempfile, cStringIO
 import email.MIMEMultipart, email.MIMEText, email.MIMEBase