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

Question

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

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

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

Answer 1

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

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

Answer 2

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

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