Как документировать код Ruby?

201

Существуют ли определенные кодовые соглашения при документировании кода ruby? Например, у меня есть следующий фрагмент кода:

require 'open3'

module ProcessUtils

  # Runs a subprocess and applies handlers for stdout and stderr
  # Params:
  # - command: command line string to be executed by the system
  # - outhandler: proc object that takes a pipe object as first and only param (may be nil)
  # - errhandler: proc object that takes a pipe object as first and only param (may be nil)
  def execute_and_handle(command, outhandler, errhandler)
    Open3.popen3(command) do |_, stdout, stderr|
      if (outhandler)
        outhandler.call(stdout)
      end
      if (errhandler)
        errhandler.call(stderr)
      end
    end
  end
end

Это предположение, что все в порядке, но, возможно, есть лучшие / превосходящие методы документирования?

ruby

— StackedCrooked
источник

У shop.oreilly.com/product/9780596516178.do есть хороший маленький пример в исходном коде. Смотрите в главе 2 листинг. Это примерно как ответ здесь. Я играл с rdoc, чтобы показать исходный код. Вы можете сделать расширение вашего файла чем-то вроде my_code.rb для my_code.rb.txt, а затем запустить на нем rdoc. > rdoc my_code.rb.txt, тогда классы и модули не будут иметь значения, потому что rdoc все равно будет отображать для него html. Веселитесь с этим.

— Дуглас Г. Аллен

198

Вы должны настроить свою документацию для процессора RDoc, который может найти вашу документацию и сгенерировать из нее HTML. Вы поместили свой комментарий в нужное место для этого, но вы должны взглянуть на документацию RDoc, чтобы узнать о видах тегов, которые RDoc знает, как форматировать. Для этого я бы переформатировал ваш комментарий следующим образом:

  # Runs a subprocess and applies handlers for stdout and stderr
  # Params:
  # +command+:: command line string to be executed by the system
  # +outhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
  # +errhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil)

— Кен Блум
источник

Как мне документировать, что параметры outhandler и errhandler могут быть равны нулю?

— StackedCrooked

10

Аннотации YARD могут быть более мощными, но пока они не включены в стандартный дистрибутив Ruby вместо RDoc, его аннотации не являются стандартными.

— Кен Блум

Ссылка RDoc не работает, попробуйте это: github.com/ruby/rdoc . Я попрошу отредактировать ответ, если все довольны этой ссылкой.

— Джордан Стюарт

27

Я настоятельно рекомендую использовать RDoc . Это в значительной степени стандарт. Легко читать комментарии к коду, и это позволяет вам легко создавать веб-документацию для вашего проекта.

— Topher Fangio
источник

24

Я бы предложил познакомиться с RDoc, как указано. Но не стоит игнорировать и очень популярный инструмент YARD A Ruby Document . Много документации, которую вы увидите в Интернете, для Ruby использует Yard. RVM знает Yard и использует его для создания документации на вашем компьютере, если она доступна.

RDoc все еще будет необходим, поскольку Yard использует его.

— vgoff
источник

1

Используя в основном C ++, Java, Scala и PHP, я нахожу @tagнотацию очень знакомой.

— Doub1ejack

1

Прошло четыре года, и YARD значительно эволюционировал. Жаль, что YARD до сих пор не включен в Ruby. (Кстати, домашняя страница

— Франклин Ю

1

Двор кажется легче, чем RDoc! Спасибо :)

— Константин Де Ла Рош

16

У Rails есть некоторые Руководства по документации API . Это, вероятно, хорошая отправная точка.

— Хэнк Гей
источник

9

Вы также можете проверить TomDoc для Ruby - версия 1.0.0-rc1.

http://tomdoc.org/

— onurozgurozkan
источник

FWIW, этот указан в руководстве по стилю GitHub - github.com/styleguide/ruby

— Майкл Пасха

Спасибо, tomdoc, кажется, хороший источник для лучших современных практик, когда дело доходит до документирования кода ruby. Отвечает на вопросы «как» и «почему», которых явно не хватает в документации по rdoc.

— Майкл Реннер,

TomDoc не был в курсе. Последний коммит был май 2012 г.

— maasha

1

@maasha К 2017 году, я полагаю, что лучшей версией, кроме простого RDoc, будет YARD, теперь, когда он анализирует контент и делает некоторые причудливые гиперссылки на классы и методы.

— Франклин Ю

2

Канонический RDoc очень похож на тот, который вы опубликовали.

Смотрите пример раздела по ссылке, которую я вам отправил

— OscarRyz
источник

2

Вот документация для системы документации ruby (RDOC)

— jrhicks
источник