Макросы не работают согласованно при создании документов - PullRequest
Новая
       48

Макросы не работают согласованно при создании документов

3 голосов
/ 01 ноября 2011

Я использую макросы в инструменте YARD doc, а некоторые файлы работают, а некоторые нет.

Например, я определяю макрос в одном из моих исходных файлов. 

# @macro [new] my_macro
# @param [String] my_string it's a string!
#
def method(my_string)
  #do stuff
end

Затем в других файлах / классах, которые у меня есть: 

#@macro my_macro
def a_method(my_string)
  #do stuff
end

Когда я запускаю генератор документов, макрос будет работать для многих файлов, но не для всех.Я предполагаю, что генератор документов не видит макрос перед созданием документов, которые потерпели неудачу.Как только он достигает макроса, он работает для каждого файла после этого.Но это предположение.

Есть ли способ убедиться, что макрос работает для каждого файла?Я подозреваю, что существует несоответствие между тем, как, по моему мнению, макросы работают в YARD и как они на самом деле работают.

PS Для тех, кто не знает, что такое ЯРД, вы должны это проверить.По сути, он делает то, что делает rDoc, но намного лучше.http://yardoc.org/

1 Ответ

4 голосов
/ 07 ноября 2011

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

yardoc "lib/foo_that_defines_buncha_macros.rb" "lib/**/*.rb"

Сначала будет обработан файл, который определяет макросы, а затем все остальные файлы. Пожалуйста, обратите внимание на кавычки, YARD выполняет свою собственную функцию, например, ** можно будет использовать (рекурсивный шар)

И да, это не будет работать, если у вас есть круговая «зависимость», то есть два файла, использующие макросы друг друга.

По словам разработчика YARD, использование двух проходов для первого получения всех макросов слишком сильно повлияет на производительность, поэтому не ожидайте, что это изменится в ближайшее время.

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

...