Github user actuaryzhang commented on a diff in the pull request:
https://github.com/apache/spark/pull/18025#discussion_r117565367
--- Diff: R/pkg/R/generics.R ---
@@ -385,6 +385,7 @@ setGeneric("value", function(bcast) {
standardGeneric("value") })
#' @return A SparkDataFrame.
#' @rdname summarize
#' @export
+#' @noRd
--- End diff --
@felixcheung I intentionally suppressed the documentation for generic
functions. The main reason is the documentation of generics conflict with
documenting groups of methods together. For example, if I document the `avg`
method for the column class together with other column aggregate methods, here
is a couple of scenarios that could happen to the generic `avg` method:
1. Without `@noRd`, roxygen will create a `avg` rd file to document the
`avg` generic method ONLY. Since in the generics definition, we don't have
`@title` or `@description`, the package won't compile.
2. Suppose we get rid of `@noRd`, and document all generics functions under
a new `generics` rd name. This will compile, but then we have conflicting
definitions of the arguments. For example, `...` could mean different things in
different generics. But this is a minor issue.
The current approach is to suppress the documentation of the generics,
since we document each method of the generics. This does not lose any
information IMO. The user can always use `getGeneric("avg")` to get the
prototype for the generics. Would like to hear your thoughts.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
