[jira] [Assigned] (SPARK-11263) lintr Throws Warnings on Commented Code in Documentation
[
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-unsubscr...@spark.apache.org
For additional commands, e-mail: issues-h...@spark.apache.org
[jira] [Assigned] (SPARK-11263) lintr Throws Warnings on Commented Code in Documentation
[
https://issues.apache.org/jira/browse/SPARK-11263?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Apache Spark reassigned SPARK-11263:
Assignee: (was: 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
>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
