a few compile() and ast doc improvements

Doc/library/ast.rst

@@ -21,13 +21,12 @@ 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.
 
-An abstract syntax tree can be generated by passing :data:`_ast.PyCF_ONLY_AST`
-as a flag to the :func:`compile` builtin function, or using the :func:`parse`
+An abstract syntax tree can be generated by passing :data:`ast.PyCF_ONLY_AST` as
+a flag to the :func:`compile` builtin function, or using the :func:`parse`
 helper provided in this module.  The result will be a tree of objects whose
-classes all inherit from :class:`ast.AST`.
+classes all inherit from :class:`ast.AST`.  An abstract syntax tree can be
+compiled into a Python code object using the built-in :func:`compile` function.
 
-A modified abstract syntax tree can be compiled into a Python code object using
-the built-in :func:`compile` function.
 
 Node classes
 ------------
@@ -126,7 +125,7 @@ and classes for traversing abstract syntax trees:
 .. function:: parse(expr, filename='<unknown>', mode='exec')
 
    Parse an expression into an AST node.  Equivalent to ``compile(expr,
-   filename, mode, PyCF_ONLY_AST)``.
+   filename, mode, ast.PyCF_ONLY_AST)``.
 
    
 .. function:: literal_eval(node_or_string)

Doc/library/functions.rst

@@ -199,15 +199,8 @@ available.  They are listed here in alphabetical order.
 
    Compile the *source* into a code or AST object.  Code objects can be executed
    by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
-   *source* can either be a string or an AST object.  Refer to the :mod:`_ast`
-   module documentation for information on how to compile into and from AST
-   objects.
-
-   When compiling a string with multi-line statements, two caveats apply: line
-   endings must be represented by a single newline character (``'\n'``), and the
-   input must be terminated by at least one newline character.  If line endings
-   are represented by ``'\r\n'``, use the string :meth:`replace` method to
-   change them into ``'\n'``.
+   *source* can either be a string or an AST object.  Refer to the :mod:`ast`
+   module documentation for information on how to work with AST objects.
 
    The *filename* argument should give the file from which the code was read;
    pass some recognizable value if it wasn't read from a file (``'<string>'`` is
@@ -237,6 +230,14 @@ available.  They are listed here in alphabetical order.
    This function raises :exc:`SyntaxError` if the compiled source is invalid,
    and :exc:`TypeError` if the source contains null bytes.
 
+   .. note::
+
+      When compiling a string with multi-line statements, line endings must be
+      represented by a single newline character (``'\n'``), and the input must
+      be terminated by at least one newline character.  If line endings are
+      represented by ``'\r\n'``, use :meth:`str.replace` to change them into
+      ``'\n'``.
+
    .. versionadded:: 2.6
       Support for compiling AST objects.