[
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: [email protected]):
[~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: [email protected]
For additional commands, e-mail: [email protected]
