Sen Fang created SPARK-11263:
--------------------------------
Summary: 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
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-unsubscr...@spark.apache.org
For additional commands, e-mail: issues-h...@spark.apache.org
