Почему нужен синтаксис ": nodoc:"?

Кажется, что многие библиотеки/плагины используют этот синтаксис:

  def self.included(base) # :nodoc:
    base.extend ClassMethods
  end

Почему нужна часть :nodoc:?

Ответы

Ответ 1

Это не обязательно. Если применяется к классу, он просто подавляет документацию (rdoc) для всех методов расширения класса. Описан в программировании Ruby как:

: nodoc: - Не включайте этот элемент в документации. Для классов и модули, методы, псевдонимы, константы и атрибуты напрямую внутри затронутого класса или модуля также будет опущено из документация. По умолчанию, однако, модулей и классов внутри этого класса или модуль будет документирован.

Ответ 2

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

Сколько раз я видел это, читая libarie-код, и я должен был спросить себя "Почему?". Я не вижу причин использовать эту функцию. Если вы не хотите, чтобы люди использовали ваш метод, просто сделайте его приватным. Это большая проблема, когда вы читаете документацию и видите вызов метода для метода, который остался без документации.