Skip to content

Commit

Permalink
Updates table
Browse files Browse the repository at this point in the history
  • Loading branch information
@eliocamp
eliocamp committed Aug 31, 2023
1 parent a333ca2 commit 04b05c8
Showing 1 changed file with 20 additions and 8 deletions.
28 changes: 20 additions & 8 deletions projects/documentation/index.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ Please label any R code chunks, especially those producing images.

In general R documentation is very good and thorough, but there's always room for improvement.

Right now there are [43 documentation-related bugs](https://bugs.r-project.org/buglist.cgi?component=Documentation&product=R&resolution=---) open in Bugzilla. Searching online and asking on social media also brings up more documentation issues that could be discussed---and possibly eventually fixed.
Right now there are [43 documentation-related bugs](https://bugs.r-project.org/buglist.cgi?component=Documentation&product=R&resolution=---) open in Bugzilla.
Searching online and asking on social media also brings up more documentation issues that could be discussed---and possibly eventually fixed.

## Proposed workflow

Expand All @@ -48,7 +49,11 @@ Sources for these issues can be:

## List of bugs

This table lists all currently open bugs with the Documentation tag sorted from oldest to newest (based on last comment). The "Location" column specifies which documentation is affected. The "Affected users" specifies which type of user I think are most likely affected by the issue (Beginners: people just starting with R, Advanced: people that use R regularly, Experts: people in close contact with R internals and/or package development). The "Action(s)" column lists the required actions to address the bug. And the "Comments" column is for general comments about the issue.
This table lists all currently open bugs with the Documentation tag sorted from oldest to newest (based on last comment).
The "Location" column specifies which documentation is affected.
The "Affected users" specifies which type of user I think are most likely affected by the issue (Beginners: people just starting with R, Advanced: people that use R regularly, Experts: people in close contact with R internals and/or package development).
The "Action(s)" column lists the required actions to address the bug.
And the "Comments" column is for general comments about the issue.

+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+----------------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| Bug ID | Title | Location | Affected users | Action(s) | Comments | Status |
Expand Down Expand Up @@ -79,7 +84,9 @@ This table lists all currently open bugs with the Documentation tag sorted from
+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+----------------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| [988](https://bugs.r-project.org/show_bug.cgi?id=988) | [input for R-intro](https://bugs.r-project.org/show_bug.cgi?id=988) | | | | | |
+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+----------------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| [15272](https://bugs.r-project.org/show_bug.cgi?id=15272) | [?nclass doesn't find the nclass help page](https://bugs.r-project.org/show_bug.cgi?id=15272) | Help docs | | create patch | The issue is confirmed and trivial to fix. | |
| [15272](https://bugs.r-project.org/show_bug.cgi?id=15272) | [?nclass doesn't find the nclass help page](https://bugs.r-project.org/show_bug.cgi?id=15272) | Help docs | | create patch | The issue is confirmed and trivial to fix. | @eliocamp |
| | | | | | | |
| | | | | | | Submited patch to fix the trivial issue but more deep issue found. |
+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+----------------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| [17695](https://bugs.r-project.org/show_bug.cgi?id=17695) | [stopifnot example does not run all the way through](https://bugs.r-project.org/show_bug.cgi?id=17695) | Help docs | Beginner | discuss | This seems to stem from the code in the `example()` function and thus the core fix needs fixing that. That might be hard. OTOH, a simpler fix would be to add a note in the example section. That'd be trivial. | |
| | | | | | | |
Expand Down Expand Up @@ -157,7 +164,7 @@ This table lists all currently open bugs with the Documentation tag sorted from
| | | | | | | |
| | | | | create patch | | |
+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+----------------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| [18350](https://bugs.r-project.org/show_bug.cgi?id=18350) | [Clarification needed in ?c](https://bugs.r-project.org/show_bug.cgi?id=18350) | Help docs | Beginner | check patch | | patch is accurate, comment submitted to bugzilla |
| [18350](https://bugs.r-project.org/show_bug.cgi?id=18350) | [Clarification needed in ?c](https://bugs.r-project.org/show_bug.cgi?id=18350) | Help docs | Beginner | check patch | | patch is accurate, comment submitted to bugzilla \| |
| | | | | | | |
| | | | | | | @phillybroadbent |
+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+----------------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
Expand Down Expand Up @@ -191,11 +198,13 @@ This table lists all currently open bugs with the Documentation tag sorted from

These are possible issues to post on Bugzilla after discussion.

- The `?iris` example section doesn't seem to be very useful. I don't understand what its doing.
- The `?iris` example section doesn't seem to be very useful.
I don't understand what its doing.

- `?formula` should link to `?update.formula`.

- The documentation of `p.adjust()` shows that the default value of `n` is `length(p)` . However, this is evaluated after `NA`s are removed from `p`, so this is not technically correct.
- The documentation of `p.adjust()` shows that the default value of `n` is `length(p)` .
However, this is evaluated after `NA`s are removed from `p`, so this is not technically correct.

- `?match` says "`%in%` is a more intuitive interface", but `match()` and `%in%` return different things.

Expand All @@ -209,15 +218,18 @@ These are possible issues to post on Bugzilla after discussion.

- Explicitly state that `rm()` is an alias for `remove()`.

- A lot of examples use `stopifnot()` to show that two things are the same. I think, this might not be great, as the user needs to know what that means.
- A lot of examples use `stopifnot()` to show that two things are the same.
I think, this might not be great, as the user needs to know what that means.

- Document the differences between factors and ordered factors in models ([https://mastodon.social/\@mccarthymg\@fosstodon.org/110685274281599336](https://mastodon.social/@[email protected]/110685274281599336)) .

- Add a discussion in `quantile()` for when the quantiles don't actually contain the correct number of observations ([https://mastodon.social/\@eliocamp/110748596295500531](https://mastodon.social/@eliocamp/110748596295500531)).

- Add a comment in `?replicate` documenting that `expr` is wrapped in an anonymous function so that assignment doesn't change the calling environment.

- Look for instances of examples using things like `if (x z<- cond1 & cond2)`. That is, using assignment inside an if statement or inside a function. These are arguably anti-patterns that shouldn't be in the help files.
- Look for instances of examples using things like `if (x z<- cond1 & cond2)`.
That is, using assignment inside an if statement or inside a function.
These are arguably anti-patterns that shouldn't be in the help files.

- `quantile()`.

Expand Down

0 comments on commit 04b05c8

Please sign in to comment.