[2.7] Update ast27 module docstring

typed_ast/ast27.py

@@ -1,17 +1,31 @@
 # -*- coding: utf-8 -*-
 """
-    ast
+    ast27
     ~~~
 
-    The `ast` module helps Python applications to process trees of the Python
+    The `ast27` module helps Python applications to process trees of the Python
     abstract syntax grammar.  The abstract syntax itself might change with
     each Python release; this module helps to find out programmatically what
-    the current grammar looks like and allows modifications of it.
-
-    An abstract syntax tree can be generated by passing `ast.PyCF_ONLY_AST` as
-    a flag to the `compile()` builtin function or by using the `parse()`
+    the current grammar looks like and allows modifications of it.  The `ast27`
+    module is similar to the builtin `ast` module on Python 2.7, except `ast27`
+    runs on Python 3 and provides PEP 484 type comments as part of the AST.
+
+    Specifically, these changes are made to the Python 2.7 AST:
+    - The `FunctionDef`, `Assign`, `For`, and `With` classes all have a
+      `type_comment` field which contains a `str` with the text of the
+      associated type comment, if any.
+    - `arguments` has a `type_comments` list of per-argument type comments.
+    - `parse` has been augmented so it can parse function signature types when
+      called with `mode=func_type`.
+    - `Module` has a `type_ignores` field which contains a list of
+      lines which have been `# type: ignore`d.
+    - `Str` has a `has_b` boolean field which indicates if the string is
+      explicitly prefixed with a `b`. (This is deprecated and may be removed in
+      future versions.)
+
+    An abstract syntax tree can be generated by using the `parse()`
     function from this module.  The result will be a tree of objects whose
-    classes all inherit from `ast.AST`.
+    classes all inherit from `ast27.AST`.
 
     A modified abstract syntax tree can be compiled into a Python code object
     using the built-in `compile()` function.
@@ -31,7 +45,7 @@
 
 def parse(source, filename='<unknown>', mode='exec'):
     """
-    Parse the source into an AST node.
+    Parse the source into an AST node with type comments.
     Equivalent to compile(source, filename, mode, PyCF_ONLY_AST).
     """
     return _ast27.parse(source, filename, mode)