API 注释 формат

В AWTK API-комментарии используются не только в качестве документации к API, но и для других целей:

• Извлечение JSON-формата IDL для генерации кода привязки на разных языках.
• Получение метаинформации о различных элементах управления для использования в дизайнере.
• Генерация кода ViewModel для MVVM.
• Создание таблицы символов для динамических библиотек.

Здесь используется формат API-комментариев, похожий на jsduck, однако jsduck не поддерживает типы данных языка C, поэтому невозможно полностью соответствовать формату jsduck.

1. Классовые комментарии

@class обозначает определение класса. Пример:

/**
 * @class progress_bar_t
 * @parent widget_t
 * @annotation ["scriptable"]
 * Прогрессивная полоса (индикатор выполнения).
 */

Здесь указано название класса, имя родительского класса и возможность его использования для скриптинга. Для классов annotation может принимать значения:

• scriptable — класс можно использовать для скриптинга;
• fake — класс является фиктивным и не существует в реальности;
• widget — класс является подклассом виджета;
• window — класс является подклассом окна;
• design — класс может использоваться в UI-дизайнере.

2. Комментарии к свойствам

@property обозначает определение свойства. Пример:

  /** 
   * @property {uint8_t} value
   * @annotation ["set_prop","get_prop","readable","persitent","design","scriptable"]
   * Значение прогресса от 0 до 100 для полосы прогресса.
   */

Здесь указаны тип переменной-члена, её название и информация о том, доступна ли она только для чтения. Для property annotation может принимать следующие значения:

• set_prop — свойство может быть установлено с помощью widget_set_prop;
• get_prop — свойство можно получить с помощью widget_get_prop;
• readable — свойство доступно для прямого чтения;
• writable — свойство можно напрямую изменить;
• persitent — свойство требует сохранения;
• design — свойство можно установить в дизайнере;
• scriptable — свойство поддерживает скриптинг.

3. Комментарии к функциям

@method обозначает определение функции. Пример:

/**
 * @method progress_bar_create
 * @annotation ["constructor", "scriptable"]
 * Создаёт объект progress_bar.
 * @param {widget_t*} parent родительский элемент управления
 * @param {xy_t} x координата X
 * @param {xy_t} y координата Y
 * @param {wh_t} w ширина
 * @param {wh_t} h высота
 *
 * @return {widget_t*} объект.
 */
widget_t* progress_bar_create(widget_t* parent, xy_t x, xy_t y, wh_t w, wh_t h);

/**
 * @method progress_bar_cast
 * Преобразует в объект progress_bar (для использования в скриптовых языках).
 * @annotation ["cast", "scriptable"]
 * @param {widget_t*} widget объект progress_bar
 *
 * @return {widget_t*} объект progress_bar.
 */
widget_t* progress_bar_cast(widget_t* widget);

/**
 * @method progress_bar_set_value
 * Устанавливает прогресс полосы.
 * @annotation ["scriptable"]
 * @param {widget_t*} виджет
 * @param {uint8_t} значение
 *
 * @return {ret_t} возвращает RET_OK при успешном выполнении, иначе — ошибку.
 */
ret_t progress_bar_set_value(widget_t* widget, uint8_t value);

Здесь указываются название функции, параметры и возвращаемое значение. Для property annotation может иметь следующие значения:

• global — функция является глобальной, если не указана как функция-член текущего класса;
• cast — функция преобразования типа;
• constructor — конструктор;
• deconstructor — деструктор;
• scriptable — функцию можно использовать в скриптах. Для специальных функций (обычно с обратными вызовами в качестве параметров) можно указать scriptable:custom и использовать пользовательский код привязки.

4. Комментарии к перечислениям

@enum обозначает определение перечисления. Пример:

/**
 * @enum align_v_t
 * @annotation ["scriptable"]
 * Определяет константы вертикального выравнивания.
 */
typedef enum _align_v_t {
  /**
   * @const ALIGN_V_NONE
   * Недействительный способ выравнивания.
   */
  ALIGN_V_NONE= 0,
  /**
   * @const ALIGN_V_MIDDLE
   * Выравнивание по центру.
   */
  ALIGN_V_MIDDLE,
  /**
   * @const ALIGN_V_TOP
   * Верхнее выравнивание.
   */
  ALIGN_V_TOP,
  /** 
   * @const ALIGN_V_BOTTOM
   * Нижнее выравнивание.
   */
  ALIGN_V_BOTTOM
}align_v_t;

Здесь определяется название перечисления и значения каждого элемента. Для enum annotation может иметь следующее значение:

• scriptable — перечисление можно использовать в скриптах.

5. Комментарии к событиям

@event обозначает определение события. Пример:

/**
 * @event {pointer_event_t} EVT_CLICK
 * Событие клика.
 */

/**
 * @event {pointer_event_t} EVT_LONG_PRESS
 * Событие длительного нажатия.
 */