Clarifications and improvements

Author: Brock Wilcox

doc/Language/syntax.pod

@@ -63,8 +63,8 @@ A semicolon after the final statement (or after the final statement inside a
 block) is optional, though it's good form to include it.
 
 A closing curly brace followed by a newline character implies a statement
-separator, which is why you don't need to write a semicolon before the last
-line in the code
+separator, which is why you don't need to write a semicolon after an C<if>
+statement block.
 
 =begin code
 if True {
@@ -76,6 +76,13 @@ say "world";
 Both semicolons are optional here, but leaving them out increases the chance
 of syntax errors when adding more lines later.
 
+You do need to include a semicolon between the C<if> block and the say statement if you want them all on one line.
+
+=begin code
+if True { say "Hello" }; say "world";
+#                     ^^^ this ; is required
+=end code
+
 =head2 Comments
 
 Comments are parts of the program text only intended for human readers, and
@@ -90,27 +97,31 @@ The most common form of comments in Perl 6 starts with a single hash character
 C<#> and goes until the end of the line.
 
 =begin code
-
 if $age > 250 {     # catch obvious outliers
     # this is another comment!
     die "That doesn't look right"
 }
 =end code
 
-=head3 Embedded comments
+=head3 Multi-line / embedded comments
 
-Embedded comments start with a hash character, followed by a backtick, and
-then some opening bracketing character, and end with the matching closing
-bracketing character.
+Multi-line and embedded comments start with a hash character, followed by a
+backtick, and then some opening bracketing character, and end with the matching
+closing bracketing character. The content can not only span multiple lines, but
+can also be embedded inline.
 
-    if #`( why would I ever write an inline comment here? ) True {
-        say "something stupid";
-    }
+=begin code
+if #`( why would I ever write an inline comment here? ) True {
+    say "something stupid";
+}
+=end code
 
 Brackets inside the comment can be nested, so in C<#`{ a { b } c }>, the
-comment goes until the very end of the string.
+comment goes until the very end of the string. You may also use more complex
+brackets, such as C<#`{{ double-curly-brace }}>, which might help disambiguate
+from nested brackets.
 
-=head3 Multiline comments
+=head3 Pod comments
 
 Pod syntax can be used for multi-line comments
 
@@ -131,26 +142,27 @@ say 'code again';
 =head2 Identifiers
 
 Identifiers are a grammatical building block that occur in several places. An
-identifier is a primitive name, and must start with an alphabetic character
-(or an underscore), followed by zero or more word characters (alphabetic,
-underscore or letter). You can also join two or more identifiers by a dash
-C<-> or a single quote C<'>, and the result is also considered to be an
-identifier.
+identifier is a primitive name, and must start with an alphabetic character (or
+an underscore), followed by zero or more word characters (alphabetic,
+underscore or number). You can also embed dashes C<-> or single quotes C<'> in
+the middle, but not two in a row.
 
     # valid identifiers:
     x
     something-longer
     with-numbers1234
     don't
+    fish-food
 
     # not valid identifiers:
     with-nubmers1234-5
     42
     is-prime?
+    fish--food
 
-Names of constants, types and routines are identifiers, and they also appear
-in variable names (optionally proceeded by a sigil; see
-L<variables|/language/variables> for more details.)
+Names of constants, types (including classes and modules) and routines (subs
+and methods) are identifiers, and they also appear in variable names (usually
+proceeded by a sigil; see L<variables|/language/variables> for more details.)
 
 =head1 Statements and Expressions
 
@@ -165,7 +177,7 @@ The C<do> prefix turns statements into expressions. So while
 
 is an error,
 
-   my $x = do if True { 42; };
+   my $x = do if True { 42 };
 
 assigns the return value of the if statement (here C<42>) to the variable
 C<$x>.
@@ -209,14 +221,14 @@ variables:
     say answer;
     #   ^^^^^^ constant
 
-    class Meta {
+    class Foo {
         method type-name {
             self.^name;
           # ^^^^ built-in term 'self'
         }
     }
-    say Meta.type-name;     # Meta
-    #   ^^^^ type name
+    say Foo.type-name;     # Foo
+    #   ^^^ type name
 
 
 =head2 Literals
@@ -375,8 +387,6 @@ A L<Regex|/type/Regex> is declared with slashes like C</foo/>. Note that this C<
 
 =head2 Declarations
 
-=comment TODO
-
 =head3 Variable declaration
 
     my $x;                          # simple lexical variable
@@ -386,7 +396,9 @@ A L<Regex|/type/Regex> is declared with slashes like C</foo/>. Note that this C<
     my Int $x where { $_ > 3 } = 7; # constrain the value based on a function
     my Int $x where * > 3 = 7;      # same constraint, but using L<Whatever> short-hand
 
-See L<Variable Declarators and Scope|http://docs.perl6.org/language/variables#Variable_Declarators_and_Scope> for more details on other scopes (our, has).
+See L<Variable Declarators and
+Scope|http://docs.perl6.org/language/variables#Variable_Declarators_and_Scope>
+for more details on other scopes (our, has).
 
 =head3 Subroutine declaration
 
@@ -403,7 +415,8 @@ You can also assign subroutines to variables.
 
 =head3 Module, Class, Role, and Grammar declaration
 
-There are several types of compilation units (packages), each declared with a keyword, a name, some optional traits, and a body of functions.
+There are several types of compilation units (packages), each declared with a
+keyword, a name, some optional traits, and a body of functions.
 
     module Gar { }
 
@@ -461,10 +474,12 @@ There are five types (arrangements) for operators, each taking either one or two
 =head2 Meta Operators
 
 Operators can be composed. A common example of this is combining an infix
-(binary) operator with assignment. You can do this with any binary operator.
+(binary) operator with assignment. You can combine assignment with any binary
+operator.
 
-    $x += 5   # Adds 5 to $x, same as $x = $x + 5
-    $x min= 3 # Sets $x to the smaller of $x and 3, same as $x = $x min 3
+    $x += 5     # Adds 5 to $x, same as $x = $x + 5
+    $x min= 3   # Sets $x to the smaller of $x and 3, same as $x = $x min 3
+    $x .= child # Equivalent to $x = $x.child
 
 Wrap an infix operator in C<[ ]> to create a new reduction operator that works
 on a single list of inputs, resulting in a single value.