skylark/syntax: Move flow statement check to the validation pass.

Mutiple other cleanups in the parser, update code documentation.

RELNOTES: None.
PiperOrigin-RevId: 167501136
diff --git a/src/test/java/com/google/devtools/build/lib/syntax/ValidationTest.java b/src/test/java/com/google/devtools/build/lib/syntax/ValidationTest.java
index 49f5dbb..51ae154 100644
--- a/src/test/java/com/google/devtools/build/lib/syntax/ValidationTest.java
+++ b/src/test/java/com/google/devtools/build/lib/syntax/ValidationTest.java
@@ -45,7 +45,7 @@
 
   @Test
   public void testReturnOutsideFunction() throws Exception {
-    checkError("Return statements must be inside a function", "return 2\n");
+    checkError("return statements must be inside a function", "return 2\n");
   }
 
   @Test