[jira] [Assigned] (SPARK-11263) lintr Throws Warnings on Commented Code in Documentation

["Apache Spark (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/SPARK-11263?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Apache Spark reassigned SPARK-11263:
------------------------------------

    Assignee: Apache Spark

> lintr Throws Warnings on Commented Code in Documentation
> --------------------------------------------------------
>
>                 Key: SPARK-11263
>                 URL: https://issues.apache.org/jira/browse/SPARK-11263
>             Project: Spark
>          Issue Type: Task
>          Components: SparkR
>            Reporter: Sen Fang
>            Assignee: Apache Spark
>            Priority: Minor
>
> This comes from a discussion in https://github.com/apache/spark/pull/9205
> Currently lintr throws many warnings around "style: Commented code should be removed."
> For example
> {code}
> R/RDD.R:260:3: style: Commented code should be removed.
> # unpersist(rdd) # rdd@@env$isCached == FALSE
>   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> R/RDD.R:283:3: style: Commented code should be removed.
> # sc <- sparkR.init()
>   ^~~~~~~~~~~~~~~~~~~
> R/RDD.R:284:3: style: Commented code should be removed.
> # setCheckpointDir(sc, "checkpoint")
>   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> {code}
> Some of them are legitimate warnings but most of them are simply code examples of functions that are not part of public API. For example
> {code}
> # @examples
> #\dontrun{
> # sc <- sparkR.init()
> # rdd <- parallelize(sc, 1:10, 2L)
> # cache(rdd)
> #}
> {code}
> One workaround is to convert them back to Roxygen doc but assign {{#' @rdname .ignore}} and Roxygen will skip these functions with message {{Skipping invalid path: .ignore.Rd}}
> That being said, I feel people usually praise/criticize R package documentation is "expert friendly". The convention seems to be providing as much documentation as possible but don't export functions that is unstable or developer only. If users choose to use them, they acknowledge the risk by using {{:::}}.



--
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