Merge branch 'master' into comments

doc/Language/5to6-nutshell.pod6

@@ -1327,7 +1327,7 @@ Synopsis 11, however it works.)
 
 The module C<Bar> now is merely a file called C<Bar.pm> with the following contents:
 
-    use v6;
+    use v6.c;
 
     sub EXPORT(*@import-list) {
         my %exportable-subs =

doc/Language/about.pod6

@@ -5,20 +5,20 @@
 =SUBTITLE Documentation for the Perl 6 Documentation Project
 
 This document collection represents the on-going effort to document the Perl 6 programming
-language with the goals of being comprehensive, easy to use, easy to
-navigate, and useful to both newcomers and experienced Perl 6
-programmers alike.
+language with the goals of being: comprehensive; easy to use; easy to
+navigate; and useful to both newcomers and experienced Perl 6
+programmers.
 
 An HTML version of the documentation is located online at
 L<https://docs.perl6.org>.
 
 The official source for this documentation is located at L<perl6/doc on
 GitHub|https://github.com/perl6/doc>.
 
-The information in this particular document is a quick overview of the process
+This particular document is a quick overview of the process
 described in more detail in L<CONTRIBUTING on GitHub|https://github.com/perl6/doc/blob/master/CONTRIBUTING.md>.
 This document also provides a short introduction to writing the Perl 6
-POD files which produce the rendered pages in HTML or other formats.
+POD files, which can be rendered into HTML and other formats.
 
 =head1 Structure
 
@@ -27,9 +27,9 @@ directory, and the C<doc/Language/> and C<doc/Type/> sub-directories.
 These files are processed as collections of definitions or
 "documentables", which are then post-processed and linked together.
 
-=head1 Generating an HTML version
+=head1 Generating HTML from POD
 
-Generating this documentation requires:
+To generate HTML from the POD files, you'll need:
 
 =item A recent version of the Rakudo Perl 6 compiler
 
@@ -42,14 +42,14 @@ of the relationships between Perl 6 types
 =item B<Optional>: L<Pygments|http://pygments.org>, for doing syntax
 highlighting
 
-Then, to generate the documentation into the C<html/> folder, run:
+To generate the documentation into the C<html/> folder, run:
 
 =begin code :skip-test
 perl6 htmlify.p6
 =end code
 
-Currently, to serve the generated documentation for your browser, Perl 5
-with Mojolicious::Lite must be installed. Then run:
+To host the documentation from a web server, have Perl 5
+and Mojolicious::Lite installed, then run:
 
 =begin code :skip-test
 perl app.pl daemon
@@ -125,10 +125,11 @@ is always considered a definition)
 
 =item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)
 
-Note that all the documentable items above should be able to be found by using the search window on
-the docs pages.  In many cases you may want to emphasize the item in bold (B<V< B<> >>) or italicized (B<V< I<> >>)
-font in addition to or in place of the code format (B<V< C<> >>).  Due to current parser limitations,
-one has to take special steps to use the B<V< X<> >> with other formatting codes.  For example:
+These items should now be searchable by using the search field in the HTML docs.
+
+You can add emphasis with bold (B<V< B<> >>) or italicized (B<V< I<> >>),
+with or without code formatting (B<V< C<> >>).  Due to current parser limitations,
+special steps have to be taken to use B<V< X<> >> with other formatting codes; for example:
 
 =begin code
 =item X<B<foo>|foo> a fancy subroutine
@@ -138,8 +139,8 @@ renders like this
 
 =item X<B<foo>|foo> a fancy subroutine
 
-Notice the text after the pipe ('|') character has no formatting.  Note also that the B<V< C<> >> construct
-used above is special in that all space inside is preserved and all text is treated verbatim.
+Notice that text after a pipe ('|') has no formatting. Also note that B<V< C<> >>
+preserves spaces and treats text as verbatim.
 
 For full details about Perl 6 POD, see L<Synopsis 26, Documentation|https://design.perl6.org/S26.html>.
 =end pod

doc/Language/classtut.pod6

@@ -8,13 +8,9 @@ X<|OOP>
 
 =comment More descriptive title?
 
-Perl 6 has a rich built in syntax for the definition and use of classes
-for object oriented programming, allowing for the definition of state
-(as L<attributes|#State>) and behaviour (as L<methods|#Methods>)
-in the objects of a class.
+Perl 6 has a rich built-in syntax for defining and using classes.
 
-A simple class is provided with a default constructor, that allows the
-setting of the attributes of the created object:
+A default constructor allows the setting of attributes for the created object:
 
     =begin code
     class Point {
@@ -37,12 +33,12 @@ setting of the attributes of the created object:
     say $r.area(); # -> 100
     =end code
 
-You are free, though, to provide your own construction and build
-implementation.  The following, more elaborate, example shows how
+You can also provide your own construction and build
+implementation.  The following, more elaborate example shows how
 a dependency handler might look in Perl 6.  It showcases custom
 constructors, private and public attributes, methods and various aspects
 of signatures. It's not very much code, and yet the result is interesting
-and, at times, useful.
+and useful.
 
     =begin code
     class Task {
@@ -96,11 +92,11 @@ X<|classes,has>
 X<|behavior>
 X<|classes,behavior>
 
-Perl 6, like many other languages, uses the C<class> keyword to introduce a
-new class.  The block that follows may contain arbitrary code, just as with
+Perl 6, like many other languages, uses the C<class> keyword to define a
+class.  The block that follows may contain arbitrary code, just as with
 any other block, but classes commonly contain state and behavior
 declarations.  The example code includes attributes (state), introduced
-through the C<has> keyword, and behaviors introduced through the C<method>
+through the C<has> keyword, and behaviors, introduced through the C<method>
 keyword.
 
 X<|type object>
@@ -141,8 +137,7 @@ X<|encapsulation>
 X<|classes,encapsulation>
 
 The first three lines inside the class block all declare attributes (called
-I<fields> or I<instance storage> in other languages).  These are storage
-locations that every instance of a class will obtain.  Just as a C<my>
+I<fields> or I<instance storage> in other languages). Just as a C<my>
 variable cannot be accessed from outside its declared scope, attributes are
 not accessible outside of the class.  This I<encapsulation> is one of the
 key principles of object oriented design.
@@ -190,7 +185,7 @@ C<$!done> and an accessor method named C<done>. It's as if you had written:
     method done() { return $!done }
 
 Note that this is not like declaring a public attribute, as some languages
-allow; you really get I<both> a private storage location and a method,
+allow; you really get I<both> a private attribute and a method,
 without having to write the method by hand. You are free instead to write
 your own accessor method, if at some future point you need to do something
 more complex than return the value.
@@ -220,7 +215,7 @@ evaluated at that time, and can even reference earlier attributes:
 
 =head1 Static fields?
 
-Perl 6 has no B<static> keyword. Nevertheless any class may declare anything
+Perl 6 has no B<static> keyword. Nevertheless, any class may declare anything
 that a module can, so making a scoped variable sounds like good idea.
 
        =begin code
@@ -310,7 +305,7 @@ example) will not repeat the task.
 
 =head2 Private Methods
 
-Analogous to attributes, methods can be private. Private methods are declared
+Just like attributes, methods can also be private. Private methods are declared
 with a prefixed exclamation mark. They are called with C<self!> followed by the
 method's name. To call a private method of another class the calling class has
 to be trusted by the called class. A trust relationship is declared with
@@ -362,10 +357,10 @@ X<|bless>
 
 The biggest difference between constructors in Perl 6 and constructors in
 languages such as C# and Java is that rather than setting up state on a
-somehow already magically created object, Perl 6 constructors actually
+somehow already magically created object, Perl 6 constructors
 create the object themselves. The easiest way to do this is by calling the
 L<bless> method, also inherited from L<Mu>. The C<bless> method expects a
-set of named parameters providing the initial values for each attribute.
+set of named parameters to provide the initial values for each attribute.
 
 The example's constructor turns positional arguments into named arguments,
 so that the class can provide a nice constructor for its users. The first
@@ -391,8 +386,8 @@ as the bind targets for C<BUILD>'s parameters. Zero-boilerplate
 initialization! See L<objects|/language/objects#Object_Construction> for
 more information.
 
-The C<BUILD> method is responsible for initializing all attributes, it must
-handle default values too:
+The C<BUILD> method is responsible for initializing all attributes and must also
+handle default values:
 
     has &!callback;
     has @!dependencies;
@@ -435,8 +430,7 @@ Unfortunately, dinner never magically happens.  It has dependent tasks:
             )
         );
 
-Notice how the custom constructor and sensible use of whitespace allows a
-layout which makes task dependencies clear.
+Notice how the custom constructor and sensible use of whitespace makes task dependencies clear.
 
 Finally, the C<perform> method call recursively calls the C<perform> method
 on the various other dependencies in order, giving the output:
@@ -453,12 +447,12 @@ on the various other dependencies in order, giving the output:
 X<|is (inheritance)>
 
 Object Oriented Programming provides the concept of inheritance as one of
-the mechanisms to allow for code reuse.  Perl 6 supports the ability for one
+the mechanisms for code reuse.  Perl 6 supports the ability for one
 class to inherit from one or more classes.  When a class inherits from
 another class it informs the method dispatcher to follow the inheritance
 chain to look for a method to dispatch.  This happens both for standard
 methods defined via the method keyword and for methods generated through
-other means such as attribute accessors.
+other means, such as attribute accessors.
 
     =begin code
     class Employee {
@@ -480,7 +474,7 @@ other means such as attribute accessors.
     }
     =end code
 
-Now any object of type Programmer can make use of the methods and accessors
+Now, any object of type Programmer can make use of the methods and accessors
 defined in the Employee class as though they were from the Programmer class.
 
     =begin code
@@ -602,7 +596,7 @@ Introspection is the process of gathering information about some objects in
 your program, not by reading the source code, but by querying the object (or
 a controlling object) for some properties, such as its type.
 
-Given an object C<$o>, and the class definitions from the previous sections,
+Given an object C<$o> and the class definitions from the previous sections,
 we can ask it a few questions:
 
     if $o ~~ Employee { say "It's an employee" };
@@ -636,7 +630,7 @@ N<For example closures cannot easily be reproduced this way; if you
 don't know what a closure is don't worry. Also current implementations have
 problems with dumping cyclic data structures this way, but they are expected
 to be handled correctly by C<.perl> at some point.>
-
+X<|^methods>
 C<$o.^methods(:local)> produces a list of L<Method|/type/Method>s that can be
 called on C<$o>. The C<:local> named argument limits the returned methods to
 those defined in the C<Programmer> class and excludes the inherited methods.
@@ -652,7 +646,7 @@ interested in. This meta class enables other ways of introspection too:
 Finally C<$o.^name> calls the C<name> method on the meta object, which
 unsurprisingly returns the class name.
 
-Introspection is very useful for debugging, and for learning the language
+Introspection is very useful for debugging and for learning the language
 and new libraries. When a function or method returns an object you don't
 know about, finding its type with C<.WHAT>, seeing a construction recipe for
 it with C<.perl>, and so on, you'll get a good idea of what its return value