templater: add brief doc about internal data types
Hopefully this will help reviewing upcoming my series. Start small.
--- a/mercurial/templater.py Tue Mar 13 11:17:10 2018 -0700
+++ b/mercurial/templater.py Mon Mar 19 21:55:02 2018 +0900
@@ -5,6 +5,47 @@
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.
+"""Slightly complicated template engine for commands and hgweb
+
+This module provides low-level interface to the template engine. See the
+formatter and cmdutil modules if you are looking for high-level functions
+such as ``cmdutil.rendertemplate(ctx, tmpl)``.
+
+Internal Data Types
+-------------------
+
+Template keywords and functions take a dictionary of current symbols and
+resources (a "mapping") and return result. Inputs and outputs must be one
+of the following data types:
+
+bytes
+ a byte string, which is generally a human-readable text in local encoding.
+
+generator
+ a lazily-evaluated byte string, which is a possibly nested generator of
+ values of any printable types, and will be folded by ``stringify()``
+ or ``flatten()``.
+
+ BUG: hgweb overloads this type for mappings (i.e. some hgweb keywords
+ returns a generator of dicts.)
+
+None
+ sometimes represents an empty value, which can be stringified to ''.
+
+True, False, int, float
+ can be stringified as such.
+
+date tuple
+ a (unixtime, offset) tuple, which produces no meaningful output by itself.
+
+hybrid
+ represents a list/dict of printable values, which can also be converted
+ to mappings by % operator.
+
+mappable
+ represents a scalar printable value, also supports % operator.
+"""
+
from __future__ import absolute_import, print_function
import os