hadley/ggplot2 — pull request #740 by BrianDiggs (2012-12-14 21:13:56+00:00)
Title: Improved aesthetic documentation

This wishlist item is inspired by a recent issue (Issue #726), an email on the help list (https://groups.google.com/d/topic/ggplot2/4rVJ1xWsLeQ/discussion), and some previous work I have done (Issue #717).

I think the documentation of aesthetics themselves needs to be overhauled/improved and I wanted to create this issue to put down some of my ideas. This has always been a thin part of the documentation. The ggplot2 book has it as Appendix B which is only 3 pages. JakeRuss added documentation of linetype, size, shape, colour, fill, and alpha in June 2011. Documentation for position, order, and group was added in January 2012. But is is jumbled and not well linked.

Here are my suggestions:

* Rename the documents/topics to start with "aesthetic" rather than "aes" to distinguish them from the `aes` family of functions (`aes`, `aes_string`, `aes_all`, `aes_auto`).
* Divide the documentation into separate topics for each aesthetic. *Very* closely related concepts (such as the position aesthetics, `hjust` and `vjust`, `colour` and `fill`) can be kept together, but `shape` and `linetype` don't belong together. For the cases with combined documentation, there should be aliases to each separately (aesthetic-hjust, for example).
* Document all the aesthetics

```r
> unique(names(aes_all(ggplot2:::.all_aesthetics)))
[1] "hjust" "alpha" "angle" "fill" "size"
[6] "colour" "group" "label" "linetype" "lower"
[11] "ymax" "middle" "ymin" "order" "shape"
[16] "radius" "sample" "upper" "vjust" "weight"
[21] "width" "x" "xend" "xmax" "xmin"
[26] "xintercept" "y" "yend" "yintercept" "z"
```

Taking out those already documented, that leaves `hjust`, `angle`, `label`, `lower`, `middle`, `radius`, `sample`, `upper`, `vjust`, `weight`, `width`, and `z` (and, according to `geom_text`, `family`, `fontface` and `lineheight`; are there others?)
* In the list of aesthetics in each geom, add links for each to its corresponding aesthetic page (the consistent naming and/or aliasing based on the aesthetic should make this template-able)

Ultimately, this will address the problem of "what does that aesthetic control?" or "why would I want to set that?" or the reverse questions of "what aesthetic controls such-and-such aspect of the plot?"

If anyone else thinks this could be useful, I'll make a branch on my clone of the repository and attach it as a pull request to which people can comment an contribute.