是否需要在R包中导出基本方法扩展？文件影响？ [英] Is it necessary to export base method extensions in an R package? Documentation implications?

问题描述

原则上，我可以保留这些扩展名不被导出，这也可以让我不要为这些已经很好记录的方法添加冗余文档，同时还通过 R CMD检查myPackage 没有任何报告警告 s。

有什么缺点吗？这可能是建议将基本方法的扩展区分在定义它们的包中吗？或者，这是否会使另一个包更难以依赖我的，如果某些核心方法扩展名不导出？

例如，如果我没有文档并且不导出以下内容：

setMethod（show，myPackageSpecialClass，function（object）{show（NA）}）

我正在尝试使用命名空间和基本方法扩展功能来细化一些更好的最佳实践细节。

解决方案

如果不导出方法，那么用户（在命令行中或试图在自己的包中使用你的类和方法通过导入）将无法使用它们 - 您的课程将显示与显示，ANY方法。

你没有记录通用的 show ，而是适合你的类的方法， show，myPackageSpecialClass-method 。如果在你的NAMESPACE你

  import（methods）
 exportMethods（show）
  

（请注意，无法导出通用程序中的某些方法），并且不提供文档， R CMD检查将抱怨

  *检查缺少的文档条目...警告
未记录的S4方法：
通用'show'和siglist'myPackageSpecialClass'
包中的所有用户级对象（包括S4类和方法）
应该有文档条目。 
请参阅编写R 
扩展手册中的编写R文档文件一章。 
  

你的例子（我知道这不是一个严肃的显示方式:)）是一个很好的说明为什么方法可能被记录 - 向用户解释为什么每次尝试显示他们得到的对象 NA ，当他们期待某种对象的描述

一种文档方法是将类中的方法分组为单个Rd文件， myPackageSpecialClass-class.Rd 。该文件将包含一个别名

  \alias {show，myPackageSpecialClass-method} 
  

和一个用法

  \S4method { show} {myPackageSpacialClass}（object）
  

只要不使用奇特的多调度，很明显，一种方法适用于哪一类。如果用户要求帮助？show ，他们总是指向方法包帮助页面。有关您的方法/类的帮助，他们需要请求该特定类型的帮助。有几种方法可以做到这一点，但我最喜欢的是

  class？ myPackageSpecialClass 
方法？ show，myPackageSpecialClass
  

这对一般用户来说不会直观; （类|方法）？ ...配方没有广泛使用，通用，签名的规范要求对S4的工作有很多了解，包括可能访问 selectMethod（show，myPackageSpecialClass）（因为该方法可能在myPackageSpecialClass继承的类上实现）或 showMethods（class =myPackageSpecialClass，其中= getNamespace（myPackage）） （因为你想知道你可以用myPackageSpecialClass做什么）。

In principle, I could keep these extensions not-exported, and this would also allow me to not-add redundant documentation for these already well-documented methods, while still also passing R CMD check myPackage without any reported WARNINGs.

What are some of the drawbacks, if any? Is this possibly recommended to keep extensions of basic methods compartmentalized within the package that defines them? Alternatively, will this make it more difficult for another package to depend on mine, if certain core method-extensions are not exported?

For example, if I don't document and don't export the following:

setMethod("show", "myPackageSpecialClass", function(object){ show(NA) })

I'm trying to flesh-out some of these finer details of best-practices with namespaces and base method extensions.

解决方案

If you don't export the methods, then users (either at the command line or trying to use your classes and methods in their own package via imports) won't be able to use them -- your class will be displayed with the show,ANY-method.

You are not documenting the generic show, but rather the method appropriate for your class, show,myPackageSpecialClass-method. If in your NAMESPACE you

import(methods)
exportMethods(show)

(note that there is no way to export just some methods on the generic show) and provide no documentation, R CMD check will complain

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
  generic 'show' and siglist 'myPackageSpecialClass'
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.
See the chapter 'Writing R documentation files' in the 'Writing R
Extensions' manual.

Your example (I know it was not meant to be a serious show method :) ) is a good illustration for why methods might be documented -- explaining to the user why every time they try and display the object they get NA, when they were expecting some kind of description about the object.

One approach to documentation is to group methods with the class into a single Rd file, myPackageSpecialClass-class.Rd. This file would contain an alias

\alias{show,myPackageSpecialClass-method}

and a Usage

\S4method{show}{myPackageSpacialClass}(object)

This works so long as no fancy multiple dispatch is used, i.e., it is clear to which class a method applies. If the user asks for help with ?show, they are always pointed toward the methods package help page. For help on your methods / class, they'd need to ask for that specific type of help. There are several ways of doing this but my favorite is

class ? myPackageSpecialClass
method ? "show,myPackageSpecialClass"

This will not be intuitive to the average user; the (class|method) ? ... formulation is not widely used, and the specification of "generic,signature" requires a lot of understanding about how S4 works, including probably a visit to selectMethod(show, "myPackageSpecialClass") (because the method might be implemented on a class that myPackageSpecialClass inherits from) or showMethods(class="myPackageSpecialClass", where=getNamespace("myPackage")) (because you're wondering what you can do with myPackageSpecialClass).

这篇关于是否需要在R包中导出基本方法扩展？文件影响？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！