[PATCH master 1/4] ht: Allow adding comment to type descriptions

[Michael Hanselmann]

This will be used to add some more details to type descriptions, e.g. on
opcode parameters or result values. The implementation is very similar
to “WithDesc”.

I chose to use “[…]” after finding “/*…*/” hard to read and spot. At
some we'll have to introduce proper formatting (e.g. using HTML).

Example with a comment:
  List of ((Length 2) and (Item 0 is (NonEmptyString [name of changed
  parameter]), item 1 is Anything))

Signed-off-by: Michael Hanselmann <han...@google.com>
---
 lib/ht.py |   30 +++++++++++++++++++++++++++++-
 1 files changed, 29 insertions(+), 1 deletions(-)

diff --git a/lib/ht.py b/lib/ht.py
index d1a8df9..4a511dc 100644
--- a/lib/ht.py
+++ b/lib/ht.py
@@ -46,7 +46,7 @@ def Parens(text):
     return "(%s)" % text
 
 
-class _DescWrapper(object):
+class _WrapperBase(object):
   __slots__ = [
     "_fn",
     "_text",
@@ -59,16 +59,31 @@ class _DescWrapper(object):
     @param fn: Wrapped function
 
     """
+    assert text.strip()
+
     self._text = text
     self._fn = fn
 
   def __call__(self, *args):
     return self._fn(*args)
 
+
+class _DescWrapper(_WrapperBase):
+  """Wrapper class for description text.
+
+  """
   def __str__(self):
     return self._text
 
 
+class _CommentWrapper(_WrapperBase):
+  """Wrapper class for comment.
+
+  """
+  def __str__(self):
+    return "%s [%s]" % (self._fn, self._text)
+
+
 def WithDesc(text):
   """Builds wrapper class with description text.
 
@@ -82,6 +97,19 @@ def WithDesc(text):
   return compat.partial(_DescWrapper, text)
 
 
+def Comment(text):
+  """Builds wrapper for adding comment to description text.
+
+  @type text: string
+  @param text: Comment text
+  @return: Callable class
+
+  """
+  assert not frozenset(text).intersection("[]")
+
+  return compat.partial(_CommentWrapper, text)
+
+
 def CombinationDesc(op, args, fn):
   """Build description for combinating operator.
 
-- 
1.7.6