Add documentation for ui_stream and ui_string files.

app/src/globals.h

@@ -44,15 +44,16 @@
 #include "utils.h"
 
 #include "parser/parser_state.h"
-
-// Zeros out all application-specific globals and SDK-specific
-// UI/exchange buffers.
+/**
+ * @brief  Zeros out all application-specific globals and SDK-specific
+ * UI/exchange buffers.
+ */
 void init_globals(void);
 
-// Toggles the persisted expert_mode setting
+/// Toggles the persisted expert_mode setting
 void toggle_expert_mode(void);
 
-// Toggles the persisted blindsigning setting
+/// Toggles the persisted blindsigning setting
 void toggle_blindsigning(void);
 
 #define MAX_APDU_SIZE      235

app/src/handle_swap.h

@@ -22,4 +22,9 @@
 
 #pragma once
 
+/**
+ * @brief Called to check the validity of swap params previously communicated
+ * by swap_copy_transaction_parameters which is called from Ledger SDK.
+ *
+ */
 void swap_check_validity(void);

app/src/keys.h

@@ -32,8 +32,11 @@
 #define MAX_BIP32_LEN  10
 #define SIGN_HASH_SIZE 32
 
-/* The values in the following enum are from the on-the-wire protocol */
-
+/**
+ * @brief The derivation type values in the following enum are from the
+ * on-the-wire protocol
+ *
+ */
 typedef enum {
     DERIVATION_TYPE_ED25519       = 0,
     DERIVATION_TYPE_SECP256K1     = 1,
@@ -53,15 +56,38 @@ typedef struct {
 } bip32_path_with_curve_t;
 
 tz_exc read_bip32_path(bip32_path_t *out, const uint8_t *in, size_t in_size);
+
+/**
+ * @brief Derive public key for given derivation type address.
+ *
+ * @param public_key Public key derived is stored in this struct.
+ * @param derivation_type Derivation type to be used
+ * @param bip32_path path to derive public key from
+ * @return tz_exc return success/failure using error code
+ */
 tz_exc derive_pk(cx_ecfp_public_key_t *public_key,
                  derivation_type_t     derivation_type,
                  const bip32_path_t   *bip32_path);
+/**
+ * @brief Derive hash of public key for given derivation type address.
+ *
+ * @param hash The hash of public key, output is stored in this buffer.
+ * @param derivation_type Derivation type to be used.
+ * @param bip32_path Path to derive public key from.
+ * @return tz_exc return Error code
+ */
 tz_exc derive_pkh(cx_ecfp_public_key_t *pubkey,
                   derivation_type_t derivation_type, char *buffer,
                   size_t len);
 void   sign(derivation_type_t derivation_type, const bip32_path_t *path,
             const uint8_t *hash, size_t hashlen, uint8_t *sig, size_t *siglen);
 
+/**
+ * @brief Check if derivation type is valid enum
+ *
+ * @param code Derivation type to check.
+ * @return validity result
+ */
 static inline bool
 check_derivation_type(derivation_type_t code)
 {

app/src/ui_commons.h

@@ -25,7 +25,10 @@
 #include <os.h>
 #include <os_io_seproxyhal.h>
 #include <ux.h>
-
+/**
+ * @brief Macro to display navigation icons and set associated callback.
+ *
+ */
 #define DISPLAY(elts, cb, len)                                              \
     memcpy(global.ux.bagls, elts, len * sizeof(bagl_element_t));            \
     G_ux.stack[0].element_arrays[0].element_array        = global.ux.bagls; \

app/src/ui_home.c

@@ -28,6 +28,10 @@
 
 static void cb(tz_ui_cb_type_t cb_type);
 
+/**
+ * @brief Callback for home screen stream.
+ *
+ * @param cb_type one of the 4 home screens (HOME, VERSION, SETTINGS, QUIT) */
 static void
 cb(tz_ui_cb_type_t cb_type)
 {

app/src/ui_home.h

@@ -20,4 +20,9 @@
 
 #pragma once
 
+/**
+ * @brief  Initialize home screen with the screen format of ledger.
+ * Internally call multiple initialization functions for Settings screen and
+ * other relevant display buffers.
+ */
 void ui_home_init(void);

app/src/ui_settings.h

@@ -7,4 +7,11 @@
 #define SETTINGS_HOME_PAGE         0
 #define SETTINGS_BLINDSIGNING_PAGE 1
 
+/**
+ * @brief Initialize settings screen for nano devices. Displays status of
+ * Expert-mode and Blind Signing.
+ *
+ * @param page Current page to display among all the pages available under
+ * Settings.
+ */
 void ui_settings_init(int16_t page);

app/src/ui_stream.h

@@ -46,9 +46,11 @@
 #include "ui_strings.h"
 
 #ifdef TARGET_NANOS
-#define TZ_UI_STREAM_HISTORY_SCREENS 5
+#define TZ_UI_STREAM_HISTORY_SCREENS \
+    5  /// Max number of screens in history for nanos
 #else
-#define TZ_UI_STREAM_HISTORY_SCREENS 8
+#define TZ_UI_STREAM_HISTORY_SCREENS \
+    8   /// Max number of screens in history for nanos2/nanox.
 #endif  // TARGET_NANOS
 
 #define TZ_UI_STREAM_TITLE_WIDTH TZ_SCREEN_WITDH_BETWEEN_ICONS_BOLD_11PX
@@ -64,10 +66,10 @@
 #define TZ_UI_STREAM_CONTENTS_SIZE \
     (TZ_UI_STREAM_CONTENTS_WIDTH * TZ_UI_STREAM_CONTENTS_LINES)
 
-/*
- * In the following structure, "cb_type" is passed to our callback and
- * it can be used to determine which screen was displayed when both
- * buttons were pressed.
+/**
+ * @brief Following #define's specify different "cb_types" which are passed to
+ * our callback and it can be used to determine which screen was displayed
+ * when both buttons were pressed.
  *
  * If TZ_UI_STREAM_SCREEN_NOCB is specified, no callback will be called
  * when both buttons are pressed.
@@ -90,8 +92,9 @@ typedef uint8_t tz_ui_cb_type_t;
 #define TZ_UI_STREAM_CB_ACCEPT             0xFFu
 
 #define TZ_UI_LAYOUT_HOME_MASK 0x80u
+
 /**
- * Layout type:
+ * @brief Layout type enum
  * BNP - refers to Bold Title, normal text/picture below the title.
  * BP  - refers to Bold tile and picture below the title(optional).
  * NP  - Normal text and picture below the text(optional)
@@ -111,10 +114,9 @@ typedef enum : uint8_t {
     TZ_UI_LAYOUT_HOME_NP  = (0x07 | TZ_UI_LAYOUT_HOME_MASK)
 } tz_ui_layout_type_t;
 
-/*
- * The icons we used are generalised to allow for seamless Stax support
+/**
+ * @brief The icons we used are generalised to allow for seamless Stax support
  */
-
 typedef uint8_t tz_ui_icon_t;
 #define TZ_UI_ICON_NONE      0x00
 #define TZ_UI_ICON_TICK      0x01
@@ -124,61 +126,155 @@ typedef uint8_t tz_ui_icon_t;
 #define TZ_UI_ICON_BACK      0x05
 #define TZ_UI_ICON_EYE       0x06
 
+/**
+ * @brief Represents a single screen's content and formatting for a ledger
+ * device.
+ *
+ */
 typedef struct {
-    tz_ui_cb_type_t cb_type;
+    tz_ui_cb_type_t
+        cb_type;  /// call back type for actions taken on this screen.
 #ifdef HAVE_BAGL
-    tz_ui_icon_t        icon;
-    tz_ui_layout_type_t layout_type;
-    char               *title;
-    char               *body[TZ_UI_STREAM_CONTENTS_LINES];
+    tz_ui_icon_t icon;  /// Icon to display on the screen.
+    tz_ui_layout_type_t
+        layout_type;  /// Layout type for the screen. CAN BP, BNP, NP, PB or
+                      /// HOME_X where X can be one of the BP, BNP, PB.
+    char *title;      /// Title to display on the screen.
+    char *body[TZ_UI_STREAM_CONTENTS_LINES];  /// Body to display on the
+                                              /// screen (Below title).
 #else
-    nbgl_layoutTagValue_t pairs[NB_MAX_DISPLAYED_PAIRS_IN_REVIEW];
-    uint8_t               nb_pairs;
+    nbgl_layoutTagValue_t
+        pairs[NB_MAX_DISPLAYED_PAIRS_IN_REVIEW];  /// Title-value pairs to be
+                                                  /// displayed on stax
+                                                  /// screen, Max 4 pairs can
+                                                  /// be displayed on one
+                                                  /// screen in stax.
+    uint8_t nb_pairs;                             /// Number of pairs to be displayed on the stax screen.
 #endif
 } tz_ui_stream_screen_t;
 
 #ifdef HAVE_NBGL
+/**
+ * @brief Holds list of title-value pairs for the current screen on stax.
+ *
+ */
 typedef struct {
     nbgl_layoutTagValueList_t list;
 } tz_ui_stream_display_t;
 #endif  // HAVE_NBGL
 
+/**
+ * @brief Holds data for current and all the history screens.
+ *
+ */
 typedef struct {
     void (*cb)(tz_ui_cb_type_t cb_type);
-    tz_ui_stream_screen_t screens[TZ_UI_STREAM_HISTORY_SCREENS];
-    tz_ui_strings_t       strings;
-    int16_t               current;
-    int16_t               total;
-    int16_t               last;
-    bool                  full;
-    bool                  pressed_right;
+    tz_ui_stream_screen_t
+        screens[TZ_UI_STREAM_HISTORY_SCREENS];  // array containing info of
+                                                // all screens.
+    tz_ui_strings_t strings;  // Ring buffer containing text data to be
+                              // displayed on screen.
+    int16_t current;          // index of current screen.
+    int16_t total;            // total number of screens.
+    int16_t last;             // index of last screen.
+    bool    full;             // true if history is full.
+    bool    pressed_right;    // true if right button was pressed.
 #ifdef HAVE_NBGL
-    tz_ui_stream_display_t current_screen;
-    char                   verify_address[TZ_BASE58CHECK_BUFFER_SIZE(20, 3)];
-    nbgl_callback_t        stream_cb;
-#endif  // HAVE_NBGL
+    tz_ui_stream_display_t
+         current_screen;  // current screen's title-value pairs.
+    char verify_address[TZ_BASE58CHECK_BUFFER_SIZE(
+        20, 3)];  //  Holds the public key..
+    nbgl_callback_t
+        stream_cb;  // callback to be called when new screen is needed.
+#endif              // HAVE_NBGL
 } tz_ui_stream_t;
 
 void tz_ui_stream_init(void (*cb)(tz_ui_cb_type_t cb_type));
-/* Push title & content to screen
- *
+
+/**
+ * @brief  Push title & content to a single screen
  * content may not always fit on screen entirely - returns total
  * bytes of content written.
+ *
+ * @param cb_type callback type for the screen being pushed.
+ * @param title title to be displayed
+ * @param value text to be displayed.
+ * @param layout_type Layout type, can be one of BP, BNP, NP, HOME_PB, ... and
+ * so on.
+ * @param icon icon to be displayed on the screen.
+ * @return size_t  size of content written on the screen.(for ex. when value
+ * is too large to fit on one screen, only part of it is written and rest is
+ * displayed on next screen.)
  */
 size_t tz_ui_stream_push(tz_ui_cb_type_t cb_type, const char *title,
                          const char *value, tz_ui_layout_type_t layout_type,
                          tz_ui_icon_t icon);
+
+/**
+ * @brief  internal implementation of tz_ui_stream_push, implemented
+ * differently for stax and nano* devices.
+ *
+ * @param cb_type callback type for the screen being pushed.
+ * @param title title to be displayed
+ * @param value text to be displayed.
+ * @param max max chars of value to be displayed. (default: -1)
+ * @param layout_type Layout type, can be one of BP, BNP, NP, HOME_PB, ... and
+ * so on.
+ * @param icon icon to be displayed on the screen.
+ * @return size_t  size of content written on the screen.(for ex. when value
+ * is too large to fit on one screen, only part of it is written and rest is
+ * displayed on next screen.)
+ */
 size_t tz_ui_stream_pushl(tz_ui_cb_type_t cb_type, const char *title,
                           const char *value, ssize_t max,
                           tz_ui_layout_type_t layout_type, tz_ui_icon_t icon);
+
+/**
+ * @brief  Push title- value pair, internally calls tz_ui_stream_push multiple
+ * times so that entire value is pushed, even if it takes multiple screens.
+ *
+ * @param cb_type callback type
+ * @param title Title to be displayed on the screen
+ * @param value text to be displayed on the screen
+ * @param layout_type Layout type
+ * @param icon Icon to be displayed on the screen
+ * @return size_t returns total number of characters written on the screen.
+ */
 size_t tz_ui_stream_push_all(tz_ui_cb_type_t cb_type, const char *title,
                              const char         *value,
                              tz_ui_layout_type_t layout_type,
                              tz_ui_icon_t        icon);
-void   tz_ui_stream_close(void);
-void   tz_ui_stream(void);
-void   tz_ui_stream_start(void);
+
+/**
+ * @brief Indicates the stream is closed. Can not close it again.
+ *
+ */
+void tz_ui_stream_close(void);
+
+/**
+ * @brief Redisplay the screen, called when additional data is pushed to the
+ * screen or when user presses buttons.
+ *
+ */
+void tz_ui_stream(void);
+
+/**
+ * @brief Start display of contents stored in ring buffer.
+ *
+ */
+void tz_ui_stream_start(void);
+
+/**
+ * @brief Get the callback type for current screen.
+ *
+ * @return tz_ui_cb_type_t
+ */
 tz_ui_cb_type_t tz_ui_stream_get_cb_type(void);
+
 #ifdef HAVE_NBGL
+/**
+ * @brief Reject confirmation screen.
+ *
+ */
 void tz_reject_ui(void);
 #endif

app/src/ui_strings.c

@@ -134,10 +134,6 @@ ui_strings_can_fit(size_t len, bool *can_fit)
     TZ_POSTAMBLE;
 }
 
-/* @param in: ptr to char[] to copy into the buffer
-   @param in_len: number of of chars to copy. in_len <= strlen(in)
-   @param out: will be set to the start of the char[] in the buffer
-*/
 void
 ui_strings_push(const char *in, size_t len, char **out)
 {
@@ -265,11 +261,6 @@ ui_strings_drop_last(char **in)
     PRINT_STRINGS;
 }
 
-/* Append as much as possible from str to the last string in the buffer.
- * This WILL NOT move `last` in the buffer.
- *
- * @param out: the start of the copied chars in the buffer.
- */
 size_t
 ui_strings_append_last(const char *str, size_t max, char **out)
 {