Качество документации ядра Ruby

Я относительно новичок в Ruby и имею ограниченное время, поэтому я пробую простые вещи. Недавно мне нужно было создать файл, и, поскольку я ленив, черт возьми, я бегу к Google. Результат:

File.open(local_filename, 'w') {|f| f.write(doc) }

Позор мне, это очень просто, должен был сделать это сам. Затем я хотел проверить, какую рубиновую магию предлагают методы класса файлов или если есть какие-либо "упрощения" при вызове этих методов, поэтому я направился в документацию здесь и проверили класс File.

  • Документация
  • 1.8.6 представляет мне "ftools.rb: дополнительные инструменты для класса файлов" в классе "Файл", чего я не ищу.
  • Документация 1.8.7 кажется ОК для класса "Файл", существует множество методов. За исключением 'open'. Документация
  • 1.9 наконец показывает мне метод "open".

И у меня был почти такой же тур с Net:: HTTP.

Я преувеличиваю, когда думаю, что хорошая старая документация Turbo Pascal 7.0 была лучше организована, чем документация Ruby прямо сейчас? Есть ли другой источник для непосвященных для сбора знаний? Или возможно, что я просто упал в дырку для документации, а остальные были супер-блестящими пятью звездами?

Спасибо

Ответы

Ответ 1

Вы должны помнить, что Ruby - это объектно-ориентированный язык, и множество объектов в стандартной библиотеке построены поверх других объектов. Кроме того, многие из них расширены модулями, которые добавляют новые функциональные возможности.

Итак, в документации вам нужно посмотреть, какие объекты встроен в объект. В случае с файлом он построен поверх IO, который будет обладать множеством функций, которые вы ожидаете найти в стандартном класс "файл".

Я согласен с тем, что некоторые из документов Ruby не связаны друг с другом. Я думаю, что важно получить хорошую книгу; Я рекомендую тот, который мы называем "The Pickaxe Book", AKA "" Программирование Ruby". Есть много других хороших книг, а также хорошая документация на линии, но это отличная книга. [Первое издание] доступно для бесплатного онлайн; Это немного устарело, но все же полезно.

Я бы рекомендовал просмотреть некоторые другие вопросы, похожие на это, на SO для получения дополнительных предложений.

Я также сохраняю ссылки на Ruby 1.9 Core и Keyword docs. И, наконец, верхняя часть сайта Ruby-Docs указывает на массу хорошей информации, хотя вам нужно обратить внимание на то, какая версия документов для.

Наконец, не игнорируйте встроенную справку: ri в командной строке - это быстрый источник информации на вашем собственном компьютере, который должен содержать документацию для основной и стандартной библиотеки, а также все драгоценности, которые у вас есть установлен. ri open сказал бы вам, что все места "открыто" определены. ri File.open предоставил бы вам много информации об этой команде.

Когда я начал с Ruby, самым большим препятствием для изучения языка была документация. Мне все еще легче получить информацию о Perl и Python, и почувствуйте, что Ruby должен использовать их в качестве примеров. Это не меняет мое удовольствие от использования Ruby. Это отличный язык, и, когда я перебираю начальный горб, мне все больше нравится.

@phoffer рекомендует RubyDoc.info в комментарии выше. Я не видел этот сайт, но он выглядит хорошо. Мне нравится, что он показывает, что класс наследует от ясно.

Ответ 2

Вы правы, есть ошибка в документации до 1.9 для File#open.

В Kernel есть open, и да, вы можете фактически сказать File.open, как вы отметили, он просто не документирован ни в File, ни в IO.

Мой совет - просто использовать 1.9 docs...

Ответ 3

Моя текущая версия - ruby ​​2.0.0 и ri 4.0.1 (ri -v). Я сталкивался с той же проблемой, когда я печатаю ri File.open = > "Ничего не известно о File.open"

После пробития интернета я нашел этот код Источник

gem rdoc --all --ri --no-rdoc

Страница также хорошо читает, почему вы должны использовать ri вместо google.

Изменить: код зафиксировал выход "Nothing known about File.open". Требуется некоторое время для установки, чтобы открыть новую вкладку.