Есть ли канонический синтаксис для типов параметров в roxygen? - PullRequest
Новая
       7

Есть ли канонический синтаксис для типов параметров в roxygen?

0 голосов
/ 27 апреля 2018

Я использую R с Roxygen. Там у вас есть @param блоки, как в Doxygen и JavaDoc. Так как R динамически типизирован (даже с утиным типом), информация о типах отсутствует, как в случае с C ++ или Java. Для PHP и Python я видел, что можно использовать @param int $n в PHPDoc и :param int n: со Sphinx (для Python).

Roxygen, похоже, не хватает этой функции, и различные руководства по стилю просто говорят что-то об описании типа (на английском). Есть ли какой-то канонический или хотя бы разумный способ стандартизировать это?

Я хотел бы получить такую ​​информацию:

  • Тип класса myClass
  • Числовой вектор длины 3
  • Именованный список, каждый из которых имеет определенные поля

Возможно, используя 

@param x A named list with fields "a", "b", and "c" which are logical. 
    These selects whether the three methods are to be used.

а точнее 

@param x Selectors for the methods "a", "b", and "c".
    (Named list of logical).

Абстрактно есть много возможностей:

  • Тип: Описание.
  • Описание. Введите.
  • (Тип) Описание.
  • ...

В Doxygen и PHPDoc я получаю третий столбец (имя параметра, тип, описание), но здесь я имею дело только с двумя столбцами. Можно ли это разумно решить в R?

1 Ответ

0 голосов
/ 27 апреля 2018

Я не уверен, что существует универсально согласованный стандарт, но одним из вариантов будет следовать синтаксису, генерируемому roxygen, при описании объектов, которые пакет делает доступными через data().

Например, если ваш пакет содержит файл data/myList.R, который содержит объект 

myList <- list (A = 1, B = 2, C = 3, D = 4)

тогда этот элемент может быть минимально задокументирован в R/data.R с использованием синтаксиса roxygen 

#' My List
#' @keywords datasets
"myList"

roxygen автоматически документирует формат объекта как

Объект класса list длиной 4.

Эта структура кажется очевидным синтаксисом, которому необходимо следовать при описании параметров, хотя это должно быть сделано вручную. Общее решение, возможно, недостижимо, поскольку некоторые функции могут обрабатывать параметры со всеми видами свойств и классов.

...