keira: add more docstrings to App class

and3rson · Mar 14, 2024 · 2d43ab0 · 2d43ab0
1 parent 77b0baf
commit 2d43ab0
Show file tree

Hide file tree

Showing 4 changed files with 19 additions and 0 deletions.
diff --git a/docs/_gen/v2_pcb.pdf b/docs/_gen/v2_pcb.pdf
diff --git a/docs/_gen/v2_schematic.pdf b/docs/_gen/v2_schematic.pdf
diff --git a/docs/keira/custom_apps.rst b/docs/keira/custom_apps.rst
@@ -26,6 +26,8 @@ Keira написана на C++, і вона містить ряд вбудов
 
 Для створення власної програми вам потрібно наслідувати клас :cpp:class:`App` та визначити метод :cpp:func:`App::run`. Цей метод буде викликатися при запуску програми.
 
+Ось перелік важливих методів та властивостей класу :cpp:class:`App`:
+
 .. doxygenclass:: App
     :members:
     :protected-members:

diff --git a/firmware/keira/src/app.h b/firmware/keira/src/app.h
@@ -39,11 +39,25 @@ class App {
     void resume();
     void stop();
     static void _run(void* data);
+    /// Повідомити ОС, що програма завершила малювання кадру.
+    ///
+    /// Цей метод слід викликати після малювання кожного кадру.
+    ///
+    /// Технічно, цей метод міняє місцями передній буфер (canvas) та задній буфер (backCanvas).
+    ///
+    /// Якщо цей метод викликається в той час, коли ОС вже малює попередній кадр, то він призведе до нетривалого блокування програми.
+    /// Іншими словами, якщо ваша програма малює кадри швидше, ніж ОС здатна їх відображати, то цей метод буде час від часу заповільнювати вашу програму.
+    /// Це не проблема, але варто про це пам'ятати.
     void queueDraw();
     const char* getName();
 
     eTaskState getState();
 
+    /// Вказівник на передній буфер для малювання.
+    ///
+    /// Програма повинна використовувати цей буфер для малювання всієї графіки.
+    ///
+    /// Після малювання, буфер потрібно відобразити на екрані за допомогою методу queueDraw().
     lilka::Canvas* canvas;
 
 protected:
@@ -66,10 +80,13 @@ class App {
     ///
     /// Програма завершується, коли цей метод завершується або робить return.
     virtual void run() = 0;
+    /// Цей метод викликається операційною системою, коли вона збирається зупинити вашу програму.
     virtual void onSuspend() {
     }
+    /// Цей метод викликається операційною системою, коли вона збирається відновити роботу вашої програми.
     virtual void onResume() {
     }
+    /// Цей метод викликається операційною системою, коли вона збирається зупинити вашу програму.
     virtual void onStop() {
     }