Блог

Я использую макросы в инструменте 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 Для тех, кто не знает, что такое YARD, вы должны проверить это. По сути, он делает то, что делает RDoc, но намного лучше. http://yardoc.org /

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

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

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

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

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

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