incorporate community feedback

Author: teunbrand

vignettes/extending-ggplot2.Rmd

@@ -47,10 +47,12 @@ A$x
 
 The majority of ggplot2 classes are immutable and static: the methods neither use nor modify state in the class. They're mostly used as a convenient way of bundling related methods together.
 
-To create a new geom or stat, you will just create a new ggproto that inherits from `Stat`, `Geom` and override the methods described below.
+When you create new functionality, like a new geom or stat, the first decision to make is whether you want to build these from scratch or you want to re-use parts of pre-exiting classes. To create a new geom or stat from scratch, you will just create a new ggproto object that inherits from `Stat` or `Geom` and override the methods described below.
 
 ## Creating a new stat
 
+Stats are an important part of layers: they instruct what is displayed, not how it is displayed. They are declared in the `layer(stat)` argument which has a correspondence to `Stat*` ggproto classes which all inherit from the root `Stat` class.
+
 ### The simplest stat
 
 We'll start by creating a very simple stat: one that gives the convex hull (the _c_ hull) of a set of points. First we create a new ggproto object that inherits from `Stat`:
@@ -68,7 +70,7 @@ StatChull <- ggproto("StatChull", Stat,
 
 The two most important components are the `compute_group()` method (which does the computation), and the `required_aes` field, which lists which aesthetics must be present in order for the stat to work.
 
-Next we write a layer function. Unfortunately, due to an early design mistake I called these either `stat_()` or `geom_()`. A better decision would have been to call them `layer_()` functions: that's a more accurate description because every layer involves a stat _and_ a geom. 
+Next we write a layer function. Unfortunately, due to an early design mistake I called these either `stat_()` or `geom_()`. A better decision would have been to call them `layer_()` functions: that's a more accurate description because every layer involves a stat _and_ a geom. Currently it is the convention to have `stat_()` wrappers with fixed `layer(stat)` arguments and `geom_()` wrappers with fixed `layer(geom)` arguments. The `stat_()` and `geom_()` functions both have the same ingredients and cook up new layers.
 
 All layer functions follow the same form - you specify defaults in the function arguments and then call the `layer()` function, sending `...` into the `params` argument. The arguments in `...` will either be arguments for the geom (if you're making a stat wrapper), arguments for the stat (if you're making a geom wrapper), or aesthetics to be set. `layer()` takes care of teasing the different parameters apart and making sure they're stored in the right place:
 
@@ -371,6 +373,8 @@ ggplot(mpg, aes(displ, drv, fill = after_stat(density))) +
 
 ## Creating a new geom
 
+Geoms are also important parts of layers: they instruct how data is displayed. They are declared in the `layer(geom)` argument which has a correspondence to `Geom*` ggproto classes which all inherit from the root `Geom` class.
+
 It's harder to create a new geom than a new stat because you also need to know some grid. ggplot2 is built on top of grid, so you'll need to know the basics of drawing with grid. If you're serious about adding a new geom, I'd recommend buying [R graphics](https://www.routledge.com/R-Graphics-Third-Edition/Murrell/p/book/9781498789059) by Paul Murrell. It tells you everything you need to know about drawing with grid.
 
 ### A simple geom
@@ -592,6 +596,7 @@ GeomLine$setup_params
 
 ## Creating your own theme
 
+Themes govern how non-data elements of the plot are displayed.
 If you're going to create your own complete theme, there are a few things you need to know:
 
 * Overriding existing elements, rather than modifying them
@@ -662,7 +667,7 @@ Complete and incomplete themes behave somewhat differently when added to a ggplo
 
 ## Creating a new faceting
 
-One of the more daunting exercises in ggplot2 extensions is to create a new faceting system. The reason for this is that when creating new facetings you take on the responsibility of how (almost) everything is drawn on the screen, and many do not have experience with directly using [gtable](https://cran.r-project.org/package=gtable) and [grid](https://cran.r-project.org/package=grid) upon which the ggplot2 rendering is built. If you decide to venture into faceting extensions, it is highly recommended to gain proficiency with the above-mentioned packages.
+Facets are a way to draw small multiples of the data in different panels. One of the more daunting exercises in ggplot2 extensions is to create a new faceting system. The reason for this is that when creating new facetings you take on the responsibility of how (almost) everything is drawn on the screen, and many do not have experience with directly using [gtable](https://cran.r-project.org/package=gtable) and [grid](https://cran.r-project.org/package=grid) upon which the ggplot2 rendering is built. If you decide to venture into faceting extensions, it is highly recommended to gain proficiency with the above-mentioned packages.
 
 The `Facet` class in ggplot2 is very powerful as it takes on responsibility of a wide range of tasks. The main tasks of a `Facet` object are: