#### Repository https://github.com/pzhaonet/beginr #### Details > The documentation level of R is already much higher than average for open source software and even than some commercial packages (esp. SPSS is notorious for its attitude of "You want to do one of these things. If you don't understand what the output means, click help and we'll pop up five lines of mumbo-jumbo that you're not going to understand either.") > > -- Peter Dalgaard > > β R-help (April 2002) Although the R package beginr is published on [CRAN](https://cran.r-project.org/package=beginr), its documentation is insufficient, only because beginr was submitted to CRAN too soon and I had no time to improve the documentation. The documentation of a function in an R package could be displayed by running the `help()` function. For example, the documentation of the `errorbar()`function in beginr can be displayed when running: ``` library('beginr') help(errorbar) ``` Then the user will see the following information: ``` Description add error bars to a scatterplot. Usage errorbar(x, y, xupper = NULL, xlower = NULL, yupper = NULL, ylower = NULL, col = "black", lty = 1) Arguments x numeric y numeric xupper numeric xlower numeric yupper numeric ylower numeric col colors lty numeric Value errorbars in a plot Examples x <- seq(0, 2 * pi, length.out = 100) y <- sin(x) plot(x, y, type = "l") errorbar(x, y, yupper = 0.1, ylower = 0.1) ``` The Description, Usage and Argument are too brief. As beginr is developed for R beginners, a detailed documentation would help. A desired example of the documentation for an R function can be found when running the following function: ``` help(sd) ``` A detailed documentation will appear as follows: ``` Standard Deviation Description This function computes the standard deviation of the values in x. If na.rm is TRUE then missing values are removed before computation proceeds. Usage sd(x, na.rm = FALSE) Arguments x a numeric vector or an R object which is coercible to one by as.double(x). na.rm logical. Should missing values be removed? Details Like var this uses denominator n - 1. The standard deviation of a zero-length vector (after removal of NAs if na.rm = TRUE) is not defined and gives an error. The standard deviation of a length-one vector is NA. See Also var for its square, and mad, the most robust alternative. Examples sd(1:2) ^ 2 ``` The task is to write a friendly documentation for each function in beginr. The suggested tool is RStudio. Open 'R/foo.R' (this file name is stupid and I will change it later) with a text editor (RStudio is recommended), and add the documentation in the header of each function. After the documentation is done, I will re-build the package, then the 'man/*.Rd' files will be updated automatically. #### Components Each function will have a detailed help information from the documentation. Open 'R/foo.R' with a text editor. Each function begins with a short description, followed by several lines beginning with `#'`, then the function body . For example, the `errorbar()` function begins at line 198, and looks like this: ``` #' add error bars to a scatterplot. #' #' @param x numeric #' @param y numeric #' @param xupper numeric #' @param xlower numeric #' @param yupper numeric #' @param ylower numeric #' @param col colors #' @param lty numeric #' #' @return errorbars in a plot #' @export #' @examples #' x <- seq(0, 2 * pi, length.out = 100) #' y <- sin(x) #' plot(x, y, type = 'l') #' errorbar(x, y, yupper = 0.1, ylower = 0.1) #' errorbar <- function(x, y, ...... ``` The first line 'add error bars to a scatterplot' is a short description about the function `errorbar()`. This description is sufficient. However, the lines beginning with `#' @param` are not sufficiently documented. For instance, line 200: ``` #' @param x numeric ``` only mentions that x should be numeric. A desired documentation for this line should be written as: ``` #' @param x A numeric vector plotted as the coordinates of points. ``` which is much better and more friendly to users. I would suggest that this task had better be claimed by an R user, because most of the '@param' lines are self-explanatory to an R expert. He/she could run the function `example(function_name)` to test each function in beginr, and get to understand what these parameters are really are. #### Deadline 30 June, 2018. #### Communication - Submit a pull request to 'github.com/pzhaonet/beginr' (recommended), - open an issue to 'github.com/pzhaonet/beginr' (recommended), - reply to this post, or - send an email to pzhao@pzhao.net #### Github https://github.com/pzhaonet
post_id | 53,122,562 |
---|---|
author | dapeng |
permlink | beginr-task-documentation |
category | utopian-io |
json_metadata | "{"users": ["param"], "app": "steemit/0.1", "tags": ["utopian-io", "task-documentation", "r", "programming", "cn-programming"], "format": "markdown", "links": ["https://github.com/pzhaonet/beginr", "https://cran.r-project.org/package=beginr", "https://github.com/pzhaonet"]}" |
created | 2018-06-15 15:30:21 |
last_update | 2018-06-16 20:33:39 |
depth | 0 |
children | 10 |
net_rshares | 0 |
last_payout | 2018-06-22 15:30:21 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 13.112 SBD |
curator_payout_value | 3.414 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 4,679 |
author_reputation | 64,235,894,740,263 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |
author_curate_reward | "" |
voter | weight | wgt% | rshares | pct | time |
---|---|---|---|---|---|
cryptos | 0 | 510,173,050 | 10% | ||
luneknight | 0 | 209,199,321 | 100% | ||
dapeng | 0 | 176,943,536,371 | 100% | ||
shenchensucc | 0 | 2,523,825,895 | 50% | ||
susanli3769 | 0 | 118,349,096,636 | 100% | ||
sweetieprincess | 0 | 24,340,721,805 | 40% | ||
alexzicky | 0 | 5,159,538,607 | 10% | ||
drunkevil | 0 | 7,335,658,725 | 29% | ||
jiangchen | 0 | 1,004,852,167 | 10% | ||
winniex | 0 | 42,202,159,230 | 100% | ||
utopian-io | 0 | 6,090,207,332,924 | 3.8% | ||
windowglass | 0 | 37,597,974,950 | 100% | ||
chann | 0 | 4,582,882,523 | 20% | ||
coindzs | 0 | 151,560,847 | 100% | ||
steemitstats | 0 | 3,635,842,958 | 5% | ||
r351574nc3 | 0 | 558,719,511 | 1.5% | ||
jjay | 0 | 457,861,094 | 66% | ||
historylover | 0 | 377,895,134 | 100% | ||
polbot | 0 | 219,550,197 | 100% | ||
ethanlee | 0 | 10,165,591,509 | 100% | ||
salty-mcgriddles | 0 | 863,473,004 | 1.5% | ||
hmayak | 0 | 216,375,792 | 100% | ||
exifr | 0 | 187,099,361 | 4% | ||
abcallen | 0 | 346,521,091 | 100% | ||
bambugrove | 0 | 149,720,021 | 30% | ||
shine.wong | 0 | 268,664,995 | 100% | ||
exifr0 | 0 | 134,478,813 | 4% | ||
sunai | 0 | 326,417,947 | 100% | ||
hitmanchoi | 0 | 58,000,930 | 20% | ||
edwardchan | 0 | 600,955,526 | 100% |
looks so great, perfect
post_id | 53,127,338 |
---|---|
author | edwardchan |
permlink | re-dapeng-beginr-task-documentation-20180615t161717766z |
category | utopian-io |
json_metadata | "{"tags": ["utopian-io"], "app": "steemit/0.1"}" |
created | 2018-06-15 16:17:18 |
last_update | 2018-06-15 16:17:18 |
depth | 1 |
children | 0 |
net_rshares | 0 |
last_payout | 2018-06-22 16:17:18 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 0.000 SBD |
curator_payout_value | 0.000 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 23 |
author_reputation | 979,740,612,916 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |
Hello @dapeng, Its great to see a documentation task request after so long. I love it. Whereas I wanted to highlight that if you could explain something more about how the documentation is to be done exactly in the package so that its easy to start with. For me after going through all the details and to the GitHub repository I was able to figure out that anyone concerned has to make changes in this file https://github.com/pzhaonet/beginr/blob/master/R/foo.R which will reflect changes here https://github.com/pzhaonet/beginr/tree/master/man. Am I right? I have never used R so I am looking from a complete beginner point of view who wants to document it. I would also like you to provide a better means of communication as I could only see your steemit username and not sure if you would be available in Discord or you could provide your email as using Github Issues to communicate for everything is not so good habit. Also as I was to perceive through your task request that you want documentation of all functions in this [file](https://github.com/pzhaonet/beginr/blob/master/R/foo.R) to be rewritten in a more beginner friendly way. So it would be great if you could do those changes to the task request and ping me here or on Utopian Discord once. > - Better explanation of how the functions are to be documented > - Providing better means of communication > - Better description of the exact part to be documented. Thanks! I love that we have a great PO making a documentation task request. These changes can surely make your TR stand out and easy to attract some good tech writers. ---- Need help? Write a ticket on https://support.utopian.io/. Chat with us on [Discord](https://discord.gg/uTyJkNm). [[utopian-moderator]](https://join.utopian.io/)
post_id | 53,210,197 |
---|---|
author | ms10398 |
permlink | re-dapeng-beginr-task-documentation-20180616t114915685z |
category | utopian-io |
json_metadata | "{"users": ["dapeng"], "links": ["https://github.com/pzhaonet/beginr/blob/master/R/foo.R", "https://github.com/pzhaonet/beginr/tree/master/man", "https://support.utopian.io/", "https://discord.gg/uTyJkNm", "https://join.utopian.io/"], "app": "steemit/0.1", "tags": ["utopian-io"]}" |
created | 2018-06-16 11:49:15 |
last_update | 2018-06-16 11:49:15 |
depth | 1 |
children | 6 |
net_rshares | 0 |
last_payout | 2018-06-23 11:49:15 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 3.000 SBD |
curator_payout_value | 0.997 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 1,774 |
author_reputation | 27,542,287,033,381 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |
author_curate_reward | "" |
voter | weight | wgt% | rshares | pct | time |
---|---|---|---|---|---|
dapeng | 0 | 67,965,066,950 | 50% | ||
knowledges | 0 | 13,810,156,596 | 100% | ||
utopian-io | 0 | 1,521,483,480,634 | 1% |
Hello @ms10398, I should have posted this post request much sooner if I knew that a moderator loves it :) Here are my explanations according to your suggestions. ## 1. Better explanation of how the functions are to be documented. You are right. Open 'R/foo.R' (this file name is stupid and I will change it later) with a text editor (RStudio is recommended), and add the documentation in the header of each function. An example is described below in No. 3. After the documentation is done, I will re-build the package, then the 'man/*.Rd' files will be updated automatically. ## 2. Providing better means of communication - submit a pull request to 'github.com/pzhaonet/beginr' (recommended), - open an issue to 'github.com/pzhaonet/beginr' (recommended), - reply to this post, or - send an email to pzhao@pzhao.net ## 3. Better description of the exact part to be documented. Open 'R/foo.R' with a text editor. Each function begins with a short description, followed by several lines beginning with `#'`, then the function body . For example, the `errorbar()` function begins at line 198, and looks like this: ``` #' add error bars to a scatterplot. #' #' @param x numeric #' @param y numeric #' @param xupper numeric #' @param xlower numeric #' @param yupper numeric #' @param ylower numeric #' @param col colors #' @param lty numeric #' #' @return errorbars in a plot #' @export #' @examples #' x <- seq(0, 2 * pi, length.out = 100) #' y <- sin(x) #' plot(x, y, type = 'l') #' errorbar(x, y, yupper = 0.1, ylower = 0.1) #' errorbar <- function(x, y, ...... ``` The first line 'add error bars to a scatterplot' is a short description about the function `errorbar()`. This description is sufficient. However, the lines beginning with `#' @param` are not sufficiently documented. For instance, line 200: ``` #' @param x numeric ``` only mentions that x should be numeric. A desired documentation for this line should be written as: ``` #' @param x A numeric vector plotted as the coordinates of points. ``` which is much better and more friendly to users. I would suggest that this task had better be claimed by an R user, because most of the '@param' lines are self-explanatory to an R expert. He/she could run the function `example(function_name)` to test each function in beginr, and get to understand what these parameters are really are. Thank you very much for your suggestions. This reply of mine will be added to this post with some revisions.
post_id | 53,253,185 |
---|---|
author | dapeng |
permlink | re-ms10398-re-dapeng-beginr-task-documentation-20180616t202722175z |
category | utopian-io |
json_metadata | "{"users": ["ms10398", "param"], "tags": ["utopian-io"], "app": "steemit/0.1"}" |
created | 2018-06-16 20:27:24 |
last_update | 2018-06-16 20:27:24 |
depth | 2 |
children | 4 |
net_rshares | 0 |
last_payout | 2018-06-23 20:27:24 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 2.802 SBD |
curator_payout_value | 0.933 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 2,473 |
author_reputation | 64,235,894,740,263 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |
author_curate_reward | "" |
voter | weight | wgt% | rshares | pct | time |
---|---|---|---|---|---|
utopian-io | 0 | 1,522,377,253,912 | 1% |
Hey @dapeng Here's a tip for your valuable feedback! @Utopian-io loves and incentivises informative comments. **Contributing on Utopian** Learn how to contribute on <a href="https://join.utopian.io">our website</a>. **Want to chat? Join us on Discord https://discord.gg/h52nFrV.** <a href="https://v2.steemconnect.com/sign/account-witness-vote?witness=utopian-io&approve=1">Vote for Utopian Witness!</a>
post_id | 53,291,943 |
---|---|
author | utopian-io |
permlink | 20180617t065715361z |
category | utopian-io |
json_metadata | "{"tags": ["utopian.tip"], "app": "utopian-io"}" |
created | 2018-06-17 06:57:15 |
last_update | 2018-06-17 06:57:15 |
depth | 3 |
children | 1 |
net_rshares | 0 |
last_payout | 2018-06-24 06:57:15 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 0.000 SBD |
curator_payout_value | 0.000 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 406 |
author_reputation | 152,913,012,544,965 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |
Thanks for the awesome explanation. I will try to spread this task request so that you can get the required documentation :) And yes we want POs to make task requests and see how wonderful it can be to get some work done by OSS contributors. While I love all TRs, but when I get a detailed version and a TR from a Dev its a beauty in itself. Thanks! Your contribution has been evaluated according to [Utopian policies and guidelines](https://join.utopian.io/guidelines), as well as a predefined set of questions pertaining to the category. To view those questions and the relevant answers related to your post, [click here](https://review.utopian.io/result/11/112211). ---- Need help? Write a ticket on https://support.utopian.io/. Chat with us on [Discord](https://discord.gg/uTyJkNm). [[utopian-moderator]](https://join.utopian.io/)
post_id | 53,292,450 |
---|---|
author | ms10398 |
permlink | re-dapeng-re-ms10398-re-dapeng-beginr-task-documentation-20180617t070453832z |
category | utopian-io |
json_metadata | "{"app": "steemit/0.1", "tags": ["utopian-io"], "links": ["https://join.utopian.io/guidelines", "https://review.utopian.io/result/11/112211", "https://support.utopian.io/", "https://discord.gg/uTyJkNm", "https://join.utopian.io/"]}" |
created | 2018-06-17 07:04:54 |
last_update | 2018-06-17 07:04:54 |
depth | 3 |
children | 1 |
net_rshares | 0 |
last_payout | 2018-06-24 07:04:54 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 0.137 SBD |
curator_payout_value | 0.044 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 843 |
author_reputation | 27,542,287,033,381 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |
author_curate_reward | "" |
voter | weight | wgt% | rshares | pct | time |
---|---|---|---|---|---|
dapeng | 0 | 82,026,804,940 | 50% |
Hey @ms10398 Here's a tip for your valuable feedback! @Utopian-io loves and incentivises informative comments. **Contributing on Utopian** Learn how to contribute on <a href="https://join.utopian.io">our website</a>. **Want to chat? Join us on Discord https://discord.gg/h52nFrV.** <a href="https://v2.steemconnect.com/sign/account-witness-vote?witness=utopian-io&approve=1">Vote for Utopian Witness!</a>
post_id | 53,470,719 |
---|---|
author | utopian-io |
permlink | 20180618t184706751z |
category | utopian-io |
json_metadata | "{"tags": ["utopian.tip"], "app": "utopian-io"}" |
created | 2018-06-18 18:47:06 |
last_update | 2018-06-18 18:47:06 |
depth | 2 |
children | 0 |
net_rshares | 0 |
last_payout | 2018-06-25 18:47:06 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 0.000 SBD |
curator_payout_value | 0.000 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 407 |
author_reputation | 152,913,012,544,965 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |
Hey @dapeng **Thanks for contributing on Utopian**. Weβre already looking forward to your next task request! **Contributing on Utopian** Learn how to contribute on <a href='https://join.utopian.io'>our website</a> or by watching <a href='https://www.youtube.com/watch?v=8S1AtrzYY1Q'>this tutorial</a> on Youtube. **Want to chat? Join us on Discord https://discord.gg/h52nFrV.** <a href='https://v2.steemconnect.com/sign/account-witness-vote?witness=utopian-io&approve=1'>Vote for Utopian Witness!</a>
post_id | 53,366,802 |
---|---|
author | utopian-io |
permlink | re-beginr-task-documentation-20180617t215508z |
category | utopian-io |
json_metadata | "{"app": "beem/0.19.29"}" |
created | 2018-06-17 21:55:09 |
last_update | 2018-06-17 21:55:09 |
depth | 1 |
children | 1 |
net_rshares | 0 |
last_payout | 2018-06-24 21:55:09 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 0.000 SBD |
curator_payout_value | 0.000 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 503 |
author_reputation | 152,913,012,544,965 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |
author_curate_reward | "" |
voter | weight | wgt% | rshares | pct | time |
---|---|---|---|---|---|
dapeng | 0 | 8,202,680,494 | 5% |
Thank you!
post_id | 53,415,302 |
---|---|
author | dapeng |
permlink | re-utopian-io-re-beginr-task-documentation-20180617t215508z-20180618t084805863z |
category | utopian-io |
json_metadata | "{"tags": ["utopian-io"], "app": "steemit/0.1"}" |
created | 2018-06-18 08:48:06 |
last_update | 2018-06-18 08:48:06 |
depth | 2 |
children | 0 |
net_rshares | 0 |
last_payout | 2018-06-25 08:48:06 |
cashout_time | 1969-12-31 23:59:59 |
total_payout_value | 0.000 SBD |
curator_payout_value | 0.000 SBD |
pending_payout_value | 0.000 SBD |
promoted | 0.000 SBD |
body_length | 10 |
author_reputation | 64,235,894,740,263 |
root_title | "[Task Request on beginr] Documentation for each function friendly to R beginners" |
beneficiaries | [] |
max_accepted_payout | 1,000,000.000 SBD |
percent_steem_dollars | 10,000 |