[jira] [Comment Edited] (SPARK-10118) Improve SparkR API docs for 1.5 release

["Yu Ishikawa (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SPARK-10118?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14707631#comment-14707631 ] 

Yu Ishikawa edited comment on SPARK-10118 at 8/21/15 11:22 PM:
---------------------------------------------------------------

[~shivaram] It seems that the Rd files of dplr and plyr were split by each function. And I asked a creater of roxygen2 if we should split functins.Rd, he answerd "that would improve readability!". And I think {{@family}} would be useful. 

h3. Suggestion
- Splits functions.Rd into each functions' Rd file
- Uses {{@family}} to relate the functions on API docs. It would be better to follow Scala {{@group}}

For example, {{add_months}} is documented:
{noformat}
##### generic.R

#' @rdname add_months
#' @export
setGeneric("add_months", function(y, x) { standardGeneric("add_months") })

##### functions.R
#' add_months
#'
#' Returns the date that is numMonths after startDate.
#'
#' @family datetime_funcs
#' @rdname add_months
#' @export
setMethod("add_months", signature(y = "Column", x = "numeric"),
          function(y, x) {
            jc <- callJStatic("org.apache.spark.sql.functions", "add_months", y@jc, as.integer(x))
            column(jc)
          })
{noformat}


h3. The Rd files of dplr and plyr
- https://github.com/hadley/dplyr/tree/master/man
- https://github.com/hadley/plyr/tree/master/man

h3. Reference of {{@family}}

{quote}
If you have a family of related functions where every function should link to every other function in the family, use @family. The value of @family should be plural.
{quote}
http://r-pkgs.had.co.nz/man.html



was (Author: yuu.ishikawa@gmail.com):
[~shivaram] It seems that the Rd files of dplr and plyr were split by each function. And I asked a creater of roxygen2 if we should split functins.Rd, he answerd "that would improve readability!". And I think {{@family}} would be useful. 

h3. Suggestion
- Splits functions.Rd into each functions' Rd file
- Uses {{@family}} to relate the functions on API docs. It would be better to follow Scala {{@group}}

For example, {{add_months}} is documented:
{noformat}
##### generic.R

#' @rdname add_months
#' @export
setGeneric("add_months", function(y, x) { standardGeneric("add_months") })

##### functions.R
#' add_months
#'
#' Returns the date that is numMonths after startDate.
#'
#' @family datetime_funcs
#' @rdname add_months
#' @export
setMethod("add_months", signature(y = "Column", x = "numeric"),
          function(y, x) {
            jc <- callJStatic("org.apache.spark.sql.functions", "add_months", y@jc, as.integer(x))
            column(jc)
          })
{noformat}


h3. The Rd files of dplr and plyr
- https://github.com/hadley/dplyr/tree/master/R
- https://github.com/hadley/plyr/tree/master/man

h3. Reference of {{@family}}

{quote}
If you have a family of related functions where every function should link to every other function in the family, use @family. The value of @family should be plural.
{quote}
http://r-pkgs.had.co.nz/man.html


> Improve SparkR API docs for 1.5 release
> ---------------------------------------
>
>                 Key: SPARK-10118
>                 URL: https://issues.apache.org/jira/browse/SPARK-10118
>             Project: Spark
>          Issue Type: Documentation
>          Components: Documentation, SparkR
>            Reporter: Shivaram Venkataraman
>
> This includes checking if the new DataFrame functions & expression show up appropriately in the roxygen docs



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@spark.apache.org
For additional commands, e-mail: issues-help@spark.apache.org