Почему нужен синтаксис ": nodoc:"?
Кажется, что многие библиотеки/плагины используют этот синтаксис:
def self.included(base) # :nodoc:
base.extend ClassMethods
end
Почему нужна часть :nodoc:
?
Ответы
Ответ 1
Это не обязательно. Если применяется к классу, он просто подавляет документацию (rdoc) для всех методов расширения класса. Описан в программировании Ruby как:
: nodoc: - Не включайте этот элемент в документации. Для классов и модули, методы, псевдонимы, константы и атрибуты напрямую внутри затронутого класса или модуля также будет опущено из документация. По умолчанию, однако, модулей и классов внутри этого класса или модуль будет документирован.
Ответ 2
Я не думаю, что это необходимо. На самом деле, на мой взгляд, это одна из самых бесполезных функций RDoc.
Сколько раз я видел это, читая libarie-код, и я должен был спросить себя "Почему?". Я не вижу причин использовать эту функцию. Если вы не хотите, чтобы люди использовали ваш метод, просто сделайте его приватным. Это большая проблема, когда вы читаете документацию и видите вызов метода для метода, который остался без документации.