Тема: Open RGSS3: Обсуждение

Ты совершенно правильно все понял. Что до вопроса:

Теперь, если мы имеем скрипт работающий с анимацией, как он будет определять с какими атрибутами работать? Мы везде будем втыкать развилки типа "if IS_XP"?

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

Сообщение от Bullet S.D.

А создатель темы согласен с тем что написано и на перенос? )

Открой глаза и почитай тему выше. )) Я теперь организатор этого действия. Если что не так, мы с Кипом обсудим отдельно.

Вообще, вроде уже просили сделать группу участников, для модерирования этого раздела. Ау, администрация?

Если кто не в курсе форум не работал, я помню. Идет настройка.

mephis
Подумай над правилами составления комментариев к методам и классам. Они должны быть компактными, но в тоже удобными и информативными. Пока пишу так:

Код:

#==============================================================================
# ** RPG::Actor
#------------------------------------------------------------------------------
#  Класс с данными актера.
#  Примечание: Актеры - это герои, главные действующие лица игры.
#==============================================================================

Код:

#--------------------------------------------------------------------------
    # ? Инициализирует переменные класса, присваивает им значения по-умолчанию
    # ! Вызывается автоматически при создании нового экземпляра
    #   класса
    #--------------------------------------------------------------------------
    def initialize

Примечание тут, возможно, излишне. А, может и нет. Но в любом случае, у метода должно быть описание. Если есть параметры - блок описания их, с учетом принимаемых типов. Тип возвращаемого значения, если оно есть.

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

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

Даже если этой системе просто скормить сырые исходники, получится вполне неплохо. См. ссылку: 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. В документации появится такая заметная сноска, что любой заметит.

Так, громоздкий вариант первого класса с кучей комментов залит:
http://rpgmaker.su/showthread.php/12...ll=1#post38410
Смотри. Думаем о надобности и виде. Документашка симпотичная. Но есть одно но - код голый оставлять тоже, не дело. Ведь редактор мы переписывать не будем (вот это уж точно без меня ). Соответственно интелисенс прикрутить не сможем. А прыгать ради каждого метода в справку и шерстить ее - будет неудобно. goto: Смотрим, думаем.

Но есть одно но - код голый оставлять тоже, не дело.

Кип, ты что-то не туда ушёл )) Документация генерируется как раз на основе комментариев. Поэтому, твой подход закомментировать всё и вся — как нельзя лучше подходит для генератора! Под сырыми исходниками я подразумевал твой закомменченный код, но без тегов yard. Т.е. генератор более-менее понимает и создаёт документацию даже без тегов. Но с тегами всё будет намного лучше. Короче говоря, в теме разработки я покажу как видоизменить комментарии RPG::Actor, чтобы и смысл сохранился и документация получилась правильная.

Тогда вопросов нет. Изучим-с и сделаемс.