[jira] [Commented] (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:comment-tabpanel=14989174#comment-14989174
]
Apache Spark commented on SPARK-11263:
--
User 'felixcheung' has created a pull request for this issue:
https://github.com/apache/spark/pull/9463
> 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
[jira] [Commented] (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:comment-tabpanel=14988023#comment-14988023
]
Shivaram Venkataraman commented on SPARK-11263:
---
I think the thing I'd like to try is to have these as #' but not mark the
function as @export. In that case are the Rd files / html files still generated
? If they are not then its probably fine to mark them as #'. I am not in favor
of publishing documentation for non-public APIs as that will only encourage
their usage, which would be a problem if we remove them later on.
> 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
[jira] [Commented] (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:comment-tabpanel=14987964#comment-14987964
]
Felix Cheung commented on SPARK-11263:
--
[~shivaram] what should we do with this? Should we convert everything to #' and
redirect to some @rdname internal_api?
> 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
[jira] [Commented] (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:comment-tabpanel=14988965#comment-14988965
]
Yu Ishikawa commented on SPARK-11263:
-
[~felixcheung] I think it would be great to ignore the commented code warnings
with the settings of lintr.
> 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
