Касаемо комментариев я не написал, потому что пока до конца не разобрался с системой автодокументирования.

Тут идея такая: чтобы люди не рыскали по сотне исходников с комментариями, а взяли и прочитали удобную документацию. Поэтому предлагаю именно этот метод. И надеюсь ты со мной согласишься.

Даже если этой системе просто скормить сырые исходники, получится вполне неплохо. См. ссылку: http://rghost.ru/15732241

Но там ещё надо докрутить шаблоны. Возможно, надо будет создать свои теги. Ближе к концу сделаю русификацию гема.

Если нужны правила, как сейчас документировать, то по этой ссылке можно почитать, какие теги и как использовать: https://github.com/lsegal/yard/wiki/Tags

Я рекомендую использовать пока только теги "@author, @param, @return, @note, @todo, @example, @attr". Покажу на примере твоего класса Numeric:

PHP код:
#===============================================================================
# Абстрактный класс для чисел.
#===============================================================================
class Numeric

  # Сравнивает число с указанными границами и, если оно выходит за пределы
  # допустимого диапазона, возвращает ближайшую границу, иначе ничего не делает
  #
  # @author Equilibrium Keeper
  # @param [Numeric] min минимальное значение
  # @param [Numeric] max максимальное значение
  # @return [Numeric]
  # @example
  #   gold = 10000
  #   gold += 15000
  #   gold = gold.limit(0, 20000)   # gold == 20000
  ##
  def limit (min, max = nil)
    result = self
    if min && self < min
      result = min
    elsif max && self > max
      result = max
    end
    return result
  end
end 
Как это будет выглядеть в документации, можешь посмотреть в том же файле, что я указал выше (см. класс Numeric).

Позже, конечно же, распишу всё подробнее в главном посте.

upd:
Кстати, твоё примечание как раз подходит для тега @note. В документации появится такая заметная сноска, что любой заметит.