Minor Documentation Fixes #2768

dpseidel · 2018-07-21T00:01:39Z

A second round of minor doc fixes throughout stack. Most of the changes are just towards consistently adding () at the end of function names throughout.

Themes documentation has required the most reworking and will be contained in a separate PR.

@batpigandme, any chance you would take a look through this 2nd massive PR of mine??? 🙏

hadley · 2018-07-22T20:01:12Z

R/geom-point.r

-#' The \emph{bubblechart} is a scatterplot with a third variable mapped to
-#' the size of points. There are no special names for scatterplots where
-#' another variable is mapped to point shape or colour, however.
+#' appropriate. A \emph{bubblechart} is a scatterplot with a third variable


_bubblechart_?

hadley · 2018-07-22T20:02:01Z

R/save.r

@@ -32,6 +32,7 @@
 #' ggsave("mtcars.pdf", width = 4, height = 4)
 #' ggsave("mtcars.pdf", width = 20, height = 20, units = "cm")
 #'
+#' # cleanup unwanted files with base unlink()


I don't think unwanted is quite the right word

hadley · 2018-07-22T20:02:49Z

R/stat-bin.r

@@ -9,15 +9,15 @@
 #'   bin width of a time variable is the number of seconds.
 #' @param bins Number of bins. Overridden by `binwidth`. Defaults to 30.
 #' @param center The center of one of the bins.  Note that if center is above or
-#'   below the range of the data, things will be shifted by an appropriate
-#'   number of `width`s. To center on integers, for example, use
+#'   below the range of the data, things will be shifted by the appropriate


It's supposed to imply that it will be shifted by an integer multiple of widths to lie within the range of the data. I'm not sure how to say that better

Might be easier to document center and boundary together?

batpigandme

Couple comments, but nothing major. Well played! 👏

batpigandme · 2018-07-23T13:08:20Z

R/geom-histogram.r

@@ -2,28 +2,28 @@
 #'
 #' Visualise the distribution of a single continuous variable by dividing
 #' the x axis into bins and counting the number of observations in each bin.
-#' Histograms (`geom_histogram`) display the count with bars; frequency
-#' polygons (`geom_freqpoly`) display the counts with lines. Frequency
+#' Histograms (`geom_histogram()`) display the count with bars; frequency


You have "Histograms…display the count" and "frequency polygons…display the counts"— I'm not partial to one or the other, I just think they should be the same.

batpigandme · 2018-07-23T13:23:47Z

R/geom-smooth.r

-#' `geom_smooth` and `stat_smooth` are effectively aliases: they
-#' both use the same arguments. Use `geom_smooth` unless you want to
+#' `geom_smooth()` and `stat_smooth()` are effectively aliases: they
+#' both use the same arguments. Use `geom_smooth()` unless you want to


Maybe state this in the positive? Use stat_smooth() if you want to display the results with a non-standard geom.

batpigandme · 2018-07-23T13:25:04Z

R/geom-text.r

@@ -10,16 +10,16 @@
 #' space they occupy on the plot is not constant in data units: when you
 #' resize a plot, labels stay the same size, but the size of the axes changes.
 #'
-#' `geom_text` and `geom_label` both add a label for each row in the
+#' `geom_text()` and `geom_label()` both add a label for each row in the


Add labels for each row? (Not wed to it one way or another, they both make sense)

batpigandme · 2018-07-23T13:27:13Z

R/labels.r

 #'
 #' You can also set axis and legend labels in the individual scales (using
-#' the first argument, the `name`). I recommend doing that if you're
+#' the first argument, the `name`). I recommend doing this if you're


Not having read through the docs as carefully as you have, I don't know the answer to this, but is use of the first-person voice common? If not, I'd switch to passive.

batpigandme · 2018-07-23T13:31:08Z

R/stat-bin.r

 #'   `width = 1` and `center = 0`, even if `0` is outside the range
 #'   of the data.  At most one of `center` and `boundary` may be
 #'   specified.
 #' @param boundary A boundary between two bins. As with `center`, things
 #'   are shifted when `boundary` is outside the range of the data. For
-#'   example, to center on integers, use `width = 1` and \code{boundary =
-#'   0.5}, even if `0.5` is outside the range of the data.  At most one of
+#'   example, to center on integers, use `width = 1` and `boundary = 0.5`,


Plus one for this being easier to describe with the center param (though you've made a valiant effort here).

batpigandme · 2018-07-23T13:31:52Z

R/stat-bin.r

-#'   example, to center on integers, use `width = 1` and \code{boundary =
-#'   0.5}, even if `0.5` is outside the range of the data.  At most one of
+#'   example, to center on integers, use `width = 1` and `boundary = 0.5`,
+#'   even if `0.5` is outside the range of the data.  At most one of


"At most one of…" just sounds off to me. Do you mean one each?

batpigandme · 2018-07-23T13:33:15Z

R/stat-smooth.r

-#'   `gam`, `loess`, `MASS::rlm`.
+#' @param method Smoothing method (function) to use, accepts either a character vector,
+#'   e.g. `"auto"`, `"lm"`, `"glm"`, `"gam"`, `"loess"` or a function, e.g.
+#'   `MASS::rlm` or `mgcv::gam`, `lm`, or `loess`.


Do you mean to have lm and loess in both places? If yes, is that because they are base functions? If so, I'd match them with MASS::rlm by prefixing with base::

batpigandme · 2018-07-23T13:34:48Z

R/stat-smooth.r

@@ -8,7 +9,7 @@
 #'   `loess` gives a better appearance, but is \eqn{O(N^{2})}{O(N^2)} in memory,
 #'   so does not work for larger datasets.
 #'
-#'   If you have fewer than 1,000 observations but want to use the same `gam`
+#'   If you have fewer than 1,000 observations but want to use the same `gam()`
 #'   model that `method = "auto"` would use then set


Comma between "use" and "then"

dpseidel · 2018-07-27T21:11:31Z

So before I merge: their was casual discussion on #2740, about tidy styling paired with a PR like this, since 79 files are already being changed so file commit histories will already be skewed. Is that something that should be considered in this same PR? or done in a separate tidying PR and merged at the same time? If it's something we want to have done, I'm happy to review a separate PR or do it myself here. If not, I'll just merge this in and discussion can continue in 2740. Thanks everyone for the feedback! I know these big PRs are tedious.

Closes tidyverse#2793

Merge remote-tracking branch 'upstream/master' into docs2.0 # Conflicts: # R/geom-text.r # man/geom_text.Rd

hadley · 2018-08-07T18:39:12Z

I don't want to think about style tidying right now, so lets shelve and think about in the future.

lock · 2019-02-04T17:52:53Z

This old issue has been automatically locked. If you believe you have found a related problem, please file a new issue (with reprex) and link to this issue. https://reprex.tidyverse.org/

A second round of minor doc fixes throughout stack

f27d242

hadley reviewed Jul 22, 2018

View reviewed changes

batpigandme approved these changes Jul 23, 2018

View reviewed changes

Final edits given feedback.

2d4e875

dpseidel added 2 commits August 1, 2018 10:38

Clarify geom_boxplot examples

f8b81d7

Closes tidyverse#2793

Merge master into docs2.0

8c57f99

Merge remote-tracking branch 'upstream/master' into docs2.0 # Conflicts: # R/geom-text.r # man/geom_text.Rd

dpseidel mentioned this pull request Aug 1, 2018

geom_boxplot + geom_jitter documentation clarity #2793

Closed

hadley approved these changes Aug 7, 2018

View reviewed changes

dpseidel merged commit 344bfea into tidyverse:master Aug 7, 2018

dpseidel deleted the docs2.0 branch August 8, 2018 17:13

lock bot locked and limited conversation to collaborators Feb 4, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Minor Documentation Fixes #2768

Minor Documentation Fixes #2768

dpseidel commented Jul 21, 2018

hadley Jul 22, 2018

hadley Jul 22, 2018

hadley Jul 22, 2018

hadley Jul 22, 2018

batpigandme left a comment

batpigandme Jul 23, 2018

batpigandme Jul 23, 2018

batpigandme Jul 23, 2018

batpigandme Jul 23, 2018

batpigandme Jul 23, 2018

batpigandme Jul 23, 2018

batpigandme Jul 23, 2018

batpigandme Jul 23, 2018

dpseidel commented Jul 27, 2018

hadley commented Aug 7, 2018

lock bot commented Feb 4, 2019

Minor Documentation Fixes #2768

Minor Documentation Fixes #2768

Conversation

dpseidel commented Jul 21, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

batpigandme left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dpseidel commented Jul 27, 2018

hadley commented Aug 7, 2018

lock bot commented Feb 4, 2019