help: add/fix docstrings for a bunch of extensions

contrib/perf.py

@@ -1,4 +1,5 @@
 # perf.py - performance test routines
+'''helper extension to measure performance'''
 
 from mercurial import cmdutil, match, commands
 import time, os, sys

hgext/acl.py

@@ -5,45 +5,45 @@
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2, incorporated herein by reference.
 #
-# this hook allows to allow or deny access to parts of a repo when
-# taking incoming changesets.
-#
-# authorization is against local user name on system where hook is
-# run, not committer of original changeset (since that is easy to
-# spoof).
-#
-# acl hook is best to use if you use hgsh to set up restricted shells
-# for authenticated users to only push to / pull from.  not safe if
-# user has interactive shell access, because they can disable hook.
-# also not safe if remote users share one local account, because then
-# no way to tell remote users apart.
-#
-# to use, configure acl extension in hgrc like this:
-#
-#   [extensions]
-#   hgext.acl =
-#
-#   [hooks]
-#   pretxnchangegroup.acl = python:hgext.acl.hook
-#
-#   [acl]
-#   sources = serve        # check if source of incoming changes in this list
-#                          # ("serve" == ssh or http, "push", "pull", "bundle")
-#
-# allow and deny lists have subtree pattern (default syntax is glob)
-# on left, user names on right. deny list checked before allow list.
-#
-#   [acl.allow]
-#   # if acl.allow not present, all users allowed by default
-#   # empty acl.allow = no users allowed
-#   docs/** = doc_writer
-#   .hgtags = release_engineer
-#
-#   [acl.deny]
-#   # if acl.deny not present, no users denied by default
-#   # empty acl.deny = all users allowed
-#   glob pattern = user4, user5
-#   ** = user6
+
+'''provide simple hooks for access control
+
+Authorization is against local user name on system where hook is run, not
+committer of original changeset (since that is easy to spoof).
+
+The acl hook is best to use if you use hgsh to set up restricted shells for
+authenticated users to only push to / pull from. It's not safe if user has
+interactive shell access, because they can disable the hook. It's also not
+safe if remote users share one local account, because then there's no way to
+tell remote users apart.
+
+To use, configure the acl extension in hgrc like this:
+
+  [extensions]
+  hgext.acl =
+
+  [hooks]
+  pretxnchangegroup.acl = python:hgext.acl.hook
+
+  [acl]
+  sources = serve        # check if source of incoming changes in this list
+                         # ("serve" == ssh or http, "push", "pull", "bundle")
+
+Allow and deny lists have a subtree pattern (default syntax is glob) on the
+left and user names on right. The deny list is checked before the allow list.
+
+  [acl.allow]
+  # if acl.allow not present, all users allowed by default
+  # empty acl.allow = no users allowed
+  docs/** = doc_writer
+  .hgtags = release_engineer
+
+  [acl.deny]
+  # if acl.deny not present, no users denied by default
+  # empty acl.deny = all users allowed
+  glob pattern = user4, user5
+   ** = user6
+'''
 
 from mercurial.i18n import _
 from mercurial import util, match

hgext/children.py

@@ -8,6 +8,8 @@
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2, incorporated herein by reference.
 
+'''provides children command to show children changesets'''
+
 from mercurial import cmdutil
 from mercurial.commands import templateopts
 from mercurial.i18n import _

hgext/extdiff.py

@@ -5,7 +5,8 @@
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2, incorporated herein by reference.
 
-'''
+'''allow external programs to compare revisions
+
 The `extdiff' Mercurial extension allows you to use external programs
 to compare revisions, or revision with working directory. The external diff
 programs are called with a configurable set of options and two

hgext/gpg.py

@@ -1,10 +1,10 @@
-# GnuPG signing extension for Mercurial
-#
 # Copyright 2005, 2006 Benoit Boissinot <benoit.boissinot@ens-lyon.org>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2, incorporated herein by reference.
 
+'''GnuPG signing extension for Mercurial'''
+
 import os, tempfile, binascii
 from mercurial import util, commands, match
 from mercurial import node as hgnode

hgext/parentrevspec.py

@@ -5,8 +5,7 @@
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2, incorporated herein by reference.
 
-'''\
-use suffixes to refer to ancestor revisions
+'''use suffixes to refer to ancestor revisions
 
 This extension allows you to use git-style suffixes to refer to the
 ancestors of a specific revision.

hgext/purge.py

@@ -23,6 +23,8 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 
+'''enable removing untracked files only'''
+
 from mercurial import util, commands, cmdutil
 from mercurial.i18n import _
 import os, stat

hgext/share.py

@@ -1,10 +1,10 @@
-# Mercurial extension to provide the 'hg share' command
-#
 # Copyright 2006, 2007 Matt Mackall <mpm@selenic.com>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2, incorporated herein by reference.
 
+'''provides the hg share command'''
+
 import os
 from mercurial.i18n import _
 from mercurial import hg, commands

hgext/win32text.py

@@ -4,31 +4,34 @@
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2, incorporated herein by reference.
-#
-# To perform automatic newline conversion, use:
-#
-# [extensions]
-# hgext.win32text =
-# [encode]
-# ** = cleverencode:
-# # or ** = macencode:
-# [decode]
-# ** = cleverdecode:
-# # or ** = macdecode:
-#
-# If not doing conversion, to make sure you do not commit CRLF/CR by
-# accident:
-#
-# [hooks]
-# pretxncommit.crlf = python:hgext.win32text.forbidcrlf
-# # or pretxncommit.cr = python:hgext.win32text.forbidcr
-#
-# To do the same check on a server to prevent CRLF/CR from being
-# pushed or pulled:
-#
-# [hooks]
-# pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
-# # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
+
+'''LF <-> CRLF/CR translation utilities
+
+To perform automatic newline conversion, use:
+
+[extensions]
+hgext.win32text =
+[encode]
+** = cleverencode:
+# or ** = macencode:
+
+[decode]
+** = cleverdecode:
+# or ** = macdecode:
+
+If not doing conversion, to make sure you do not commit CRLF/CR by accident:
+
+[hooks]
+pretxncommit.crlf = python:hgext.win32text.forbidcrlf
+# or pretxncommit.cr = python:hgext.win32text.forbidcr
+
+To do the same check on a server to prevent CRLF/CR from being
+pushed or pulled:
+
+[hooks]
+pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
+# or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
+'''
 
 from mercurial.i18n import _
 from mercurial.node import short