Рефакторинг, добавление документации

utils.h

@@ -130,24 +130,9 @@ struct robot_regs {
 
 // NOTE первой командой на любую транзакцию должна стоять команда опустить траверсу (в 22 зоне по идее никогда не закончим)
 struct robot_code {
-    short barrel_id; // нужен ID барабана, если
+    short barrel_id; // если требуются операции с барабаном, то для корректного исполнения нужно указать значение >= 0
     short PC; // когда -1, код не выполняется
-
-    /*
-     * система команд, которая нужна: (квадратные скобки - аргумент это младшие 14 бит)
-     * 0 (смещение: да () ? нет): установить смещение (да - встанет в смещенную позицию, нет - в точную)
-     * 1 (опция с барабаном) [поднять (1) | опустить]: поднять/опустить траверсу (перед поднятием ожидать если таймер барабана не истек)
-     * 2 (опция с барабаном) [зона]: съебаться в зону
-     * 3 [сек]: пауза на нужное количество секунд
-     * 4 [время]: установить таймер барабану
-     * 5 (ETCH(1) | GAL (2)) [зона]: установить зону блокировки, умеет использовать автоинкримент зоны гальваники или обезжиривания
-     * 6 [X(1) | Y(2)]: скорректировать ось
-     * 15: конец
-     *
-     * формат команды: (команда, старший байт) [младший байт, аргумент команды (если есть)] [слово, аргумент если команда требует]
-     */
     unsigned short code[16]; // формат кода: [команды] <команда 0>
-
 };
 
 
@@ -252,6 +237,8 @@ extern short scheduler_stage;
 extern const short NIGHT_ZONES[9];
 
 
+/* ======================== ROBOT CODE ======================== */
+
 #define ROBOT_CMD_MASK                 0xF000U
 #define ROBOT_CMD_END_code             0x0000U
 #define ROBOT_CMD_MOVE_TO_ZONE_code    0x1000U
@@ -302,7 +289,7 @@ extern const short NIGHT_ZONES[9];
 #define ROBOT_CMD_INC_ZONE(arg) (ROBOT_CMD_INC_ZONE_code | (unsigned short)(arg))
 
 
-/* ======================== DISABLED ZONES DEFS ======================== */
+/* ======================== DISABLED ZONES ======================== */
 
 #define DISABLED_ETCH_1 0x0001
 #define DISABLED_ETCH_2 0x0002
@@ -318,7 +305,8 @@ extern const short NIGHT_ZONES[9];
 #define DISABLED_GAL_8  0x0200
 #define DISABLED_GAL    0x03FC
 
-/* ======================== IO DEFS ======================== */
+
+/* ======================== IO ======================== */
 
 #define ROBOT1_X 1
 #define ROBOT1_Z 2
@@ -329,8 +317,6 @@ extern const short NIGHT_ZONES[9];
 #define VFD_REG_D0_ADDR 4096
 #define VFD_REG_M0_ADDR 2048
 
-/* ======================== ROBOT DEFS ======================== */
-
 #define MB_CMD_WRITE_FLAG 5
 #define MB_CMD_WRITE_REG 6
 
@@ -376,6 +362,13 @@ extern const short NIGHT_ZONES[9];
 #define ROBOT_X_TARGET_ZONE_ADDR (VFD_REG_D0_ADDR + ROBOT_X_TARGET_ZONE_OFFSET)
 
 
+/* ======================== UTILS FUNCTIONS ======================== */
+
+/**
+ * Занята ли зона. Учитываются только барабаны, которые внизу
+ * @param zone зона для обнаружения
+ * @return true если занята, в противном случае false
+ */
 char zone_is_busy(short zone);
 
 
@@ -383,14 +376,38 @@ char zone_is_busy(short zone);
 #define ROBOT_2 2
 #define ROBOT_NONE -1
 
+/**
+ * Функция, определяющая можно ли переместить барабан и куда его нужно переместить.
+ * @param bar указатель на барабан
+ * @param robot_id ID робота, нужно передавать всегда, в режиме одного робота учитывается время, в режиме двух роботов
+ * учитываются рабочие границы роботов. Для отключения учета времени и границ следует передать <code>ROBOT_NONE</code>.
+ * @return Зону, куда нужно переместить барабан. Если значение < 0, то барабан переместить в данный момент невозможно.
+ */
 short can_move(struct barrel *bar, char robot_id);
 
+/**
+ * Получить приоритет для операции перемещения барабана. Учитывает взаимное положение барабанов на линии и аттрибуты барабана
+ * @note Вызывать следует только если барабан подлежит перемещению (<code>can_move</code> вернул значение >= 0)
+ * @param barrel_id номер барабана, для которого нужно вычислить приоритет.
+ * @return Приоритет операции. Чем больше число тем выше приоритет.
+ */
 short get_operation_priority(short barrel_id);
 
+/**
+ * Удаление барабана из зоны, учитывает блокировку барабана роботом и положение барабана (нельзя удалить висящий барабан).
+ * @param zone Зона, из которой требуется удалить барабана.
+ * @return true, если барабан был удален, в противном случае false.
+ */
 char remove_barrel_from_zone(short zone);
 
-void create_operation(struct robot_code *code, const short barrel_id, const short start_zone, const short dest_zone,
-                      const short current_zone, const short robot_id);
+/**
+ * Создание операции на перемещение барабана.
+ * @param barrel_id индекс барабана в структуре барабана, функцией напрямую не учитывается, но копируется в структуру кода робота
+ * @param start_zone зона, откуда нужно переместить барабан
+ * @param dest_zone зона, куда нужно переместить барабан (если ZONE_PASSIVATION то фактически после операции барабан окажется в зоне промывки 4а)
+ * @param robot_id ID робота, который должен выполнить операцию
+ */
+void create_operation(short barrel_id, const short start_zone, const short dest_zone, const short robot_id);
 
 /**
  * Активна ли зона цинкования или травления
@@ -406,9 +423,19 @@ char is_accessible_zone(short zone);
  */
 char increment_zone(short zone);
 
+/**
+ * Получение первой ночной зоны, то есть зоны куда нужно ложить ночной барабан
+ * @return номер зоны, либо -1 если зона занята или еще нужна для обслуживания других барабанов
+ */
 short get_first_night_zone();
 
 #ifdef EMULATOR
+/**
+ * Вывод структуры кода робота, работает только в эмуляторе.
+ * @param code структура кода робота, именно ее и будет выводить функция
+ * @param robot_id ID робота (1 или 2), нужно для вывода отладочной информации
+ * @param fd file descriptor, устройство куда нужно записать весь вывод
+ */
 void debug_print_robot_code(const struct robot_code *code, const short robot_id, int fd);
 #endif