docs: добавь поясняющие комментарии к модулям и инструментам

c/set-protocol/ports/stm32g474-usb-boot/boot_writer.h

@@ -1,3 +1,9 @@
+/*
+ * Накопление неполного 64-битного слова Flash STM32G474 между пакетами. ECC требует
+ * программировать слово один раз; только последний хвост дополняется 0xFF, а длина исходного
+ * образа остаётся неизменной.
+ */
+
 #ifndef G474_BOOT_WRITER_H
 #define G474_BOOT_WRITER_H
 #include <stdbool.h>
@@ -17,6 +23,9 @@ static inline void g474_writer_init(g474_writer *w, uint32_t size)
     memset(w, 0, sizeof(*w)); w->size = size;
     memset(w->pending, 0xff, sizeof(w->pending));
 }
+/* offset и length описывают байты исходного образа. Хвост пакета остаётся
+ * в pending до следующего вызова; повтор или перестановка пакетов запрещены.
+ * После отказа program контекст помечается failed до новой инициализации. */
 static inline bool g474_writer_write(g474_writer *w, uint32_t offset,
     const uint8_t *data, uint16_t length, g474_program_word program, void *user)
 {
@@ -26,6 +35,8 @@ static inline bool g474_writer_write(g474_writer *w, uint32_t offset,
         w->pending[w->used++] = *data++; ++w->received;
         if (w->used == 8 || w->received == w->size) {
             uint64_t word;
+            /* Адрес берётся от начала накопленного слова, а не от границы
+             * текущего пакета, которая может проходить внутри этого слова. */
             uint32_t start = w->received - w->used;
             memcpy(&word, w->pending, sizeof(word));
             if (!program(user, start, word)) { w->failed = true; return false; }