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

Question

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

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

Почему необходима :nodoc: часть?

Answer 1

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

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

Answer 2

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

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