ht: Allow adding comment to type descriptions

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 <hansmi@google.com>
Reviewed-by: René Nussbaumer <rn@google.com>

diff --git a/lib/ht.py b/lib/ht.py
index d1a8df9..4a511dc 100644 (file)
--- 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.