Нужно ли экспортировать расширения базовых методов в R-пакет?Последствия для документации? - PullRequest
Новая
       48

Нужно ли экспортировать расширения базовых методов в R-пакет?Последствия для документации?

4 голосов
/ 20 января 2012

В принципе, я мог бы сохранить эти расширения неэкспортированными, и это также позволило бы мне не добавлять избыточную документацию для этих уже хорошо документированных методов, в то же время передавая R CMD check myPackage без каких-либо сообщений WARNING s.

Каковы некоторые недостатки, если таковые имеются? Возможно ли, рекомендуется, чтобы расширения базовых методов были разделены внутри пакета, который их определяет? Или же это затруднит зависимость другого пакета от моего, если некоторые основные расширения метода не экспортируются?

Например, если я не документирую и не экспортирую следующее:

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

Я пытаюсь конкретизировать некоторые из этих тонких деталей лучших практик с помощью пространств имен и расширений базовых методов.

1 Ответ

4 голосов
/ 20 января 2012

Если вы не экспортируете методы, то пользователи (либо из командной строки, либо пытаясь использовать ваши классы и методы в своем собственном пакете с помощью импорта) не смогут их использовать - ваш класс будет отображатьсяс show,ANY-method.

Вы документируете не общий show, а метод, подходящий для вашего класса, show,myPackageSpecialClass-method.Если в вашем NAMESPACE вы 

import(methods)
exportMethods(show)

(обратите внимание, что в общем шоу нет возможности экспортировать только некоторые методы) и не предоставили документацию, R CMD check будет жаловаться 

* 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.

Ваш пример (я знаю, что это не был серьезный метод показа :)) является хорошей иллюстрацией того, почему методы могут быть задокументированы - объяснение пользователю, почему каждый раз, когда они пытаются отобразить объект, он получает NA, когдаони ожидали какого-то описания объекта.

Один из подходов к документации - сгруппировать методы с классом в один файл Rd, myPackageSpecialClass-class.Rd.Этот файл будет содержать псевдоним 

\alias{show,myPackageSpecialClass-method}

и использование 

\S4method{show}{myPackageSpacialClass}(object)

. Это работает, если не используется причудливая множественная диспетчеризация, т. Е. Ясно, к какому классу применяется метод,Если пользователь запрашивает справку по ?show, он всегда указывает на страницу справки пакета методов.Чтобы получить помощь по вашим методам / классам, им нужно будет обратиться за помощью к этому конкретному типу помощи.Есть несколько способов сделать это, но мой любимый это 

class ? myPackageSpecialClass
method ? "show,myPackageSpecialClass"

Это не будет интуитивно понятным для обычного пользователя;(класс | метод)?... формулировка широко не используется, а спецификация "generic, signature" требует большого понимания того, как работает S4, включая, вероятно, посещение selectMethod(show, "myPackageSpecialClass") (поскольку метод может быть реализован в классе, от которого наследуется myPackageSpecialClass) или showMethods(class="myPackageSpecialClass", where=getNamespace("myPackage")) (потому что вам интересно, что вы можете сделать с помощью myPackageSpecialClass).

...