[PATCH 1 of 2] templater: add consistent docstrings to functions

[Gregory Szorc]

# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1427944783 25200
#      Wed Apr 01 20:19:43 2015 -0700
# Node ID 450d5d8893a0481fc430cfa0a74c58a9c1cd1a2d
# Parent  37a2b446985f2ef77b9690a0548c8630828b7412
templater: add consistent docstrings to functions

The content of "hg help templating" is largely derived from docstrings
on functions providing functionality. Template functions are the long
holdout.

Prepare for generating them dynamically by defining docstrings for all
template functions.

There are numerous ways these docs could be improved. Right now, the
help output simply shows function names and arguments. So literally
any accurate data is better than what is there now.

diff --git a/mercurial/templater.py b/mercurial/templater.py
--- a/mercurial/templater.py
+++ b/mercurial/templater.py
@@ -218,8 +218,10 @@ def buildfunc(exp, context):
         return (runfilter, (args[0][0], args[0][1], f))
     raise error.ParseError(_("unknown function '%s'") % n)
 
 def date(context, mapping, args):
+    """:date(date[, fmt]): Format a date. See :hg:`help dates` for formatting
+    strings."""
     if not (1 <= len(args) <= 2):
         # i18n: "date" is a keyword
         raise error.ParseError(_("date expects one or two arguments"))
 
@@ -229,8 +231,10 @@ def date(context, mapping, args):
         return util.datestr(date, fmt)
     return util.datestr(date)
 
 def diff(context, mapping, args):
+    """:diff([includepattern [, excludepattern]]): Show a diff, optionally
+    specifying files to include or exclude."""
     if len(args) > 2:
         # i18n: "diff" is a keyword
         raise error.ParseError(_("diff expects one, two or no arguments"))
 
@@ -246,8 +250,10 @@ def diff(context, mapping, args):
 
     return ''.join(chunks)
 
 def fill(context, mapping, args):
+    """:fill(text[, width[, initialident[, hangindent]]]): Fill many
+    paragraphs with optional indentation. See the "fill" filter."""
     if not (1 <= len(args) <= 4):
         # i18n: "fill" is a keyword
         raise error.ParseError(_("fill expects one to four arguments"))
 
@@ -269,10 +275,10 @@ def fill(context, mapping, args):
 
     return templatefilters.fill(text, width, initindent, hangindent)
 
 def pad(context, mapping, args):
-    """usage: pad(text, width, fillchar=' ', right=False)
-    """
+    """:pad(text, width[, fillchar=' '[, right=False]]): Pad text with a
+    fill character."""
     if not (2 <= len(args) <= 4):
         # i18n: "pad" is a keyword
         raise error.ParseError(_("pad() expects two to four arguments"))
 
@@ -295,8 +301,11 @@ def pad(context, mapping, args):
     else:
         return text.ljust(width, fillchar)
 
 def get(context, mapping, args):
+    """:get(dict, key): Get an attribute/key from an object. Some keywords
+    are complex types. This function allows you to obtain the value of an
+    attribute on these type."""
     if len(args) != 2:
         # i18n: "get" is a keyword
         raise error.ParseError(_("get() expects two arguments"))
 
@@ -316,8 +325,10 @@ def _evalifliteral(arg, context, mapping
     else:
         yield t
 
 def if_(context, mapping, args):
+    """:if(expr, then[, else]): Conditionally execute based on the result of
+    an expression."""
     if not (2 <= len(args) <= 3):
         # i18n: "if" is a keyword
         raise error.ParseError(_("if expects two or three arguments"))
 
@@ -327,8 +338,10 @@ def if_(context, mapping, args):
     elif len(args) == 3:
         yield _evalifliteral(args[2], context, mapping)
 
 def ifcontains(context, mapping, args):
+    """:ifcontains(search, thing, then[, else]): Conditionally execute based
+    on whether the item "search" is in "thing"."""
     if not (3 <= len(args) <= 4):
         # i18n: "ifcontains" is a keyword
         raise error.ParseError(_("ifcontains expects three or four arguments"))
 
@@ -340,8 +353,10 @@ def ifcontains(context, mapping, args):
     elif len(args) == 4:
         yield _evalifliteral(args[3], context, mapping)
 
 def ifeq(context, mapping, args):
+    """:ifeq(expr1, expr2, then[, else]): Conditionally execute based on
+    whether 2 items are equivalent."""
     if not (3 <= len(args) <= 4):
         # i18n: "ifeq" is a keyword
         raise error.ParseError(_("ifeq expects three or four arguments"))
 
@@ -352,8 +367,9 @@ def ifeq(context, mapping, args):
     elif len(args) == 4:
         yield _evalifliteral(args[3], context, mapping)
 
 def join(context, mapping, args):
+    """:join(list, sep): Join items in a list with a delimiter."""
     if not (1 <= len(args) <= 2):
         # i18n: "join" is a keyword
         raise error.ParseError(_("join expects one or two arguments"))
 
@@ -374,18 +390,21 @@ def join(context, mapping, args):
             yield joiner
         yield x
 
 def label(context, mapping, args):
+    """:label(label, expr): Apply a label to generated content. Content with
+    a label applied can result in additional post-processing, such as
+    automatic colorization."""
     if len(args) != 2:
         # i18n: "label" is a keyword
         raise error.ParseError(_("label expects two arguments"))
 
     # ignore args[0] (the label string) since this is supposed to be a a no-op
     yield _evalifliteral(args[1], context, mapping)
 
 def revset(context, mapping, args):
-    """usage: revset(query[, formatargs...])
-    """
+    """:revset(query[, formatargs...]): Execute a revision set query. See
+    :hg:`help revset`."""
     if not len(args) > 0:
         # i18n: "revset" is a keyword
         raise error.ParseError(_("revset expects one or more arguments"))
 
@@ -412,8 +431,9 @@ def revset(context, mapping, args):
 
     return templatekw.showlist("revision", revs, **mapping)
 
 def rstdoc(context, mapping, args):
+    """:rstdoc(text, style): Format ReStructuredText."""
     if len(args) != 2:
         # i18n: "rstdoc" is a keyword
         raise error.ParseError(_("rstdoc expects two arguments"))
 
@@ -422,10 +442,10 @@ def rstdoc(context, mapping, args):
 
     return minirst.format(text, style=style, keep=['verbose'])
 
 def shortest(context, mapping, args):
-    """usage: shortest(node, minlength=4)
-    """
+    """:shortest(node, minlength=4): Obtain the shortest representation of
+    a node."""
     if not (1 <= len(args) <= 2):
         # i18n: "shortest" is a keyword
         raise error.ParseError(_("shortest() expects one or two arguments"))
 
@@ -474,8 +494,9 @@ def shortest(context, mapping, args):
             if len(shortest) <= length:
                 return shortest
 
 def strip(context, mapping, args):
+    """:strip(text[, chars]): Strip characters from a string."""
     if not (1 <= len(args) <= 2):
         # i18n: "strip" is a keyword
         raise error.ParseError(_("strip expects one or two arguments"))
 
@@ -485,8 +506,10 @@ def strip(context, mapping, args):
         return text.strip(chars)
     return text.strip()
 
 def sub(context, mapping, args):
+    """:sub(pattern, replacement, expression): Perform text substitution
+    using regular expressions."""
     if len(args) != 3:
         # i18n: "sub" is a keyword
         raise error.ParseError(_("sub expects three arguments"))
 
@@ -495,8 +518,10 @@ def sub(context, mapping, args):
     src = stringify(_evalifliteral(args[2], context, mapping))
     yield re.sub(pat, rpl, src)
 
 def startswith(context, mapping, args):
+    """:startswith(pattern, text): Returns the value from the "text" argument
+    if it begins with the content from the "pattern" argument."""
     if len(args) != 2:
         # i18n: "startswith" is a keyword
         raise error.ParseError(_("startswith expects two arguments"))
 
@@ -507,9 +532,9 @@ def startswith(context, mapping, args):
     return ''
 
 
 def word(context, mapping, args):
-    """return nth word from a string"""
+    """:word(number, text[, separator]): Return the nth word from a string."""
     if not (2 <= len(args) <= 3):
         # i18n: "word" is a keyword
         raise error.ParseError(_("word expects two or three arguments, got %d")
                                % len(args))