Merge branch 'master' of github.com:perl6/doc

Author: paultcochrane

lib/Language/functions.pod

@@ -256,7 +256,30 @@ attach to the outer routine.
 
 =head1 Defining Operators
 
-TODO
+Operators are just subroutines with funny names. The funny names are composed
+of the category name (C<infix>, C<prefix>, C<postfix>, C<circumfix>,
+C<postcircumfix>), followed by a colon, and a list of the operator name or
+names (two components in the case of circumfix and postcircumfix).
+
+This works both for adding multi candidates to existing operators, and for
+defining new ones. In the latter case, the definition of the new subroutine
+automatically installs the new operator into the grammar, but only in the
+current lexical scope. Importing an operator via C<use> or C<import> also
+makes it available.
+
+=begin code
+# adding a multi candidate to an existing operator:
+multi infix:<+>(Int $x, "same") { 2 * $x };
+say 21 + "same",            # 42
+
+# defining a new operator
+sub postfix:<!>(Int $x where { $x >= 0 }) { [*] 1..$x };
+say 6!;                     # 720
+=end code
+
+=begin comment
+TODO: elaborate on (post)circumfix ops
+=end comment
 
 =head2 Precedence
 

lib/Language/operators.pod

@@ -90,8 +90,8 @@ Operators can occur in several positions relative to a term:
 
 =end table
 
-Each operator is also available as a routine; postcircumfix operators as
-methods, all others as subroutines. The name of the routine is formed of
+Each operator is also available as a subroutine.
+The name of the routine is formed of
 the operator category, then a colon, and a list quote construct with the
 symbol(s) that make up the operator:
 
@@ -103,8 +103,9 @@ term or as a prefix. Subroutine calls are the most common listops. Other
 cases include meta-reduced infix operators (C<[+]| 1, 2, 3>) and the
 L<#prefix ...> etc. stub operators.
 
-(Niecza currently turns postcircumfix operators in a subroutine call,
-while Rakudo interprets them as methods).
+
+Defining custom operators is covered in
+L</language/functions#Defining Operators>.
 
 =head1 Z<>Term Precedence