Move example text to the line after the example label.

braincore · braincore · commit c7282e632a10 · 2016-05-20T11:04:42.000-07:00
Test Plan: Added test.

Reviewed By: krieb
diff --git a/babelapi/babel/parser.py b/babelapi/babel/parser.py
@@ -843,11 +843,9 @@ def p_examples_add(self, p):
 
     # It's possible for no example fields to be specified.
     def p_example(self, p):
-        """example : KEYWORD ID STRING NEWLINE INDENT example_fields DEDENT
-                   | KEYWORD ID empty NEWLINE INDENT example_fields DEDENT
-                   | KEYWORD ID STRING NEWLINE
-                   | KEYWORD ID empty NEWLINE"""
-        if len(p) > 5:
+        """example : KEYWORD ID NEWLINE INDENT docsection example_fields DEDENT
+                   | KEYWORD ID NEWLINE"""
+        if len(p) > 4:
             seen_fields = set()
             for example_field in p[6]:
                 if example_field.name in seen_fields:
@@ -857,11 +855,11 @@ def p_example(self, p):
                         p.lineno(1), self.path))
                 seen_fields.add(example_field.name)
             p[0] = BabelExample(
-                self.path, p.lineno(1), p.lexpos(1), p[2], p[3],
+                self.path, p.lineno(1), p.lexpos(1), p[2], p[5],
                 OrderedDict((f.name, f) for f in p[6]))
         else:
             p[0] = BabelExample(
-                self.path, p.lineno(1), p.lexpos(1), p[2], p[3], OrderedDict())
+                self.path, p.lineno(1), p.lexpos(1), p[2], None, OrderedDict())
 
     def p_example_fields_create(self, p):
         'example_fields : example_field'
diff --git a/babelapi/data_type.py b/babelapi/data_type.py
@@ -780,7 +780,7 @@ def __init__(self, label, text, value, token=None):
         assert isinstance(label, six.text_type), type(label)
         self.label = label
         assert isinstance(text, (six.text_type, type(None))), type(text)
-        self.text = text
+        self.text = doc_unwrap(text) if text else text
         assert isinstance(value, (six.text_type, OrderedDict)), type(value)
         self.value = value
         self._token = token
diff --git a/doc/lang_ref.rst b/doc/lang_ref.rst
@@ -39,7 +39,8 @@ The spec should live in a file called ``users.babel``::
         status Status
             "The status of the account."
 
-        example default "A regular user"
+        example default
+            "A regular user"
             account_id="id-48sa2f0"
             email="alex@example.org"
             name="Alexander the Great"
@@ -297,10 +298,9 @@ examples help demonstrate how distinct fields might interact with each other.
 Generators have access to examples, which is useful when automatically
 generating documentation.
 
-An example is declared by using the ``example`` keyword followed by a label
-and optionally a descriptive string. By convention, "default" should
-be used as the label name for an example that can be considered a good
-representation of the general case for the type::
+An example is declared by using the ``example`` keyword followed by a label.
+By convention, "default" should be used as the label name for an example that
+can be considered a good representation of the general case for the type::
 
     struct Account extends BasicAccount
         "Information about a user's account."
@@ -310,13 +310,15 @@ representation of the general case for the type::
         status Status
             "The status of the account."
 
-        example default "A regular user"
+        example default
+            "A regular user"
             account_id = "id-48sa2f0"
             email = "alex@example.org"
             name = "Alexander the Great"
             status = active
 
-        example unnamed "An anonymous user"
+        example unnamed
+            "An anonymous user"
             account_id = "id-29sk2p1"
             email = "anony@example.org"
             name = null
@@ -326,6 +328,9 @@ Every required field (not nullable and no default) must be specified, otherwise
 an error will be returned. ``null`` can be used to mark that a nullable type
 is not present.
 
+An optional multi-line documentation string can be specified after the line
+declaring the example and before the example fields.
+
 When you have a set of nested types, each type defines examples for its fields
 with primitive types. For fields with composite types, the value of the example
 must be a label of an example in the target composite type. Here's an example
diff --git a/test/test_babel.py b/test/test_babel.py
@@ -2278,6 +2278,48 @@ def test_examples_union(self):
             "Bad example for field 'a': example of void type must be null",
             cm.exception.msg)
 
+    def test_examples_text(self):
+        # Test multi-line example text (verify it gets unwrapp-ed)
+        text = textwrap.dedent("""\
+            namespace test
+
+            struct S
+                a String
+
+                example default
+                    "This is the text for the example.
+                    And I guess it's kind of long."
+                    a = "Hello, World."
+            """)
+        t = TowerOfBabel([('test.babel', text)])
+        t.parse()
+        s_dt = t.api.namespaces['test'].data_type_by_name['S']
+        example = s_dt.get_examples()['default']
+        self.assertEqual(
+            example.text,
+            "This is the text for the example. And I guess it's kind of long.")
+
+        # Test union example
+        text = textwrap.dedent("""\
+            namespace test
+
+            union U
+                a
+                b String
+
+                example default
+                    "This is the text for the example.
+                    And I guess it's kind of long."
+                    b = "Hi, World."
+            """)
+        t = TowerOfBabel([('test.babel', text)])
+        t.parse()
+        u_dt = t.api.namespaces['test'].data_type_by_name['U']
+        example = u_dt.get_examples()['default']
+        self.assertEqual(
+            example.text,
+            "This is the text for the example. And I guess it's kind of long.")
+
     def test_examples_enumerated_subtypes(self):
         # Test missing custom example
         text = textwrap.dedent("""\
