Improve clarity of docstring for ggplot()

[kevinxperese]

• changed "component" to "components"
• used "pattern" instead of "way" and "method"
• broke each pattern description in to separate paragraph used more explicit names in example code
• used more explicit data frame and variable names in example code
• added more explicit comments in example code
• removed error bars in last pattern of example code (and removed standard deviations from the summary stats calculated)

[teunbrand]

Thanks, I appreciate the effort!
However, there are some issues with the examples for which I've left suggestions. I apologise if they're nit-picky. If you have any questions, please feel free to ask.

[teunbrand]

Come to think of it, there is also a 4th pattern that is useful in some circumstances. That is to put a partial mapping in ggplot() and complete it in the layers, e.g.:

ggplot(mapping = aes(x = group)) +
  geom_point(mapping = aes(y = value), data = sample_df) +
  geom_point(
    mapping = aes(y = group_mean), data = group_means_df,
    colour = 'red', size = 3
  )

I'm not convinced it should be in the docs though.

[kevinxperese]

I'm not convinced it should be in the docs though.

I think I agree.
The description for ggplot() has:

There are three common patterns used to invoke ggplot()

I don't know what the threshold is for "common," though. (My brain went down the rabbit hole of wanting to actually attempt to quantify the distribution of these four patterns!)

[teunbrand]

Thanks for all your efforts is clarifying these patterns!

I think there is GitHub magic to automatically propagate these changes to the manual pages, but in case that fails: could I ask you to run devtools::document()?

/document

[kevinxperese]

Thanks so much, @teunbrand, for iterating on this with me -- I very much appreciate ALL your work on this project!!!

[teunbrand]

No thank you for contributing: I think the patterns are much clearer now, so that will be helpful for people who're trying to learn ggplot2!