docs: improve docs for smart_notification and structural_navi

Change-Id: Ia28d58f32bdb0d28d4c1022b103dab2a6165afbc

diff --git a/include/smart_notification.h b/include/smart_notification.h
index 1f62150..85b027e 100644 (file)
--- a/include/smart_notification.h
+++ b/include/smart_notification.h
@@ -1,7 +1,15 @@
-#include "screen_reader.h"
-#include "screen_reader_haptic.h"
-#include "logger.h"
+#ifndef SMART_NOTIFICATION_H_
+#define SMART_NOTIFICATION_H_
 
+/**
+ * @brief Type of notification events.
+ *
+ * @FOCUS_CHAIN_END_NOTIFICATION_EVENT emitted when
+ * currnetly focued or highlighted widget is the last one
+ * in focus chain for application current view.
+ *
+ * @REALIZED_ITEMS_NOTIFICATION_EVENT
+ */
 enum _Notification_Type {
      FOCUS_CHAIN_END_NOTIFICATION_EVENT,
      REALIZED_ITEMS_NOTIFICATION_EVENT,
@@ -9,6 +17,46 @@ enum _Notification_Type {
 
 typedef enum _Notification_Type Notification_Type;
 
+/**
+ * @brief Initializes notification submodule.
+ *
+ * @description
+ * Notification submodule is resposnisle for providing
+ * voice output to end user when on of following events
+ * occur:
+ *
+ * 1. User starts scrolling active application view.
+ * 2. User finished scrolling (and all scrolling related
+ *    animations has stopped) active application view.
+ * 3. When user has navigated to the last widget in focus
+ *    chain.
+ * 4. After scrolling lists, some of item becomes visible
+ *
+ * @nore
+ * 1 and 2 are handled internally by smart navigation submodule.
+ * about events 3 and 4 submodule has to be informed by the developer
+ * by using smart_notification API.
+ */
 void smart_notification_init(void);
+
+/**
+ * @brief Notifies smart_notification about UI event.
+ *
+ * @param nt Type of the occured event.
+ * @param start_index Item of the first item that becomes visible
+ * after scrolling list widget.
+ * @param end_index index of the last item that becomes visible
+ * after scrolling list widget.
+ *
+ * @note start_index and end_index are interpreted only
+ * when nt parameter is REALIZED_ITEMS_NOTIFICATION_EVENT
+ * @note initializes haptic module.
+ */
 void smart_notification(Notification_Type nt, int start_index, int end_index);
+
+/**
+ * @brief Shutdowns notification subsystem.
+ */
 void smart_notification_shutdown(void);
+
+#endif /* end of include guard: SMART_NOTIFICATION_H_ */

diff --git a/include/structural_navi.h b/include/structural_navi.h
index 64db592..655e3bf 100644 (file)
--- a/include/structural_navi.h
+++ b/include/structural_navi.h
@@ -3,13 +3,90 @@
 
 #include <atspi/atspi.h>
 
+/**
+ * @brief Structural navigation submodule.
+ *
+ * @detail
+ * Structural navigation submodule can be used to traverse at-spi object tree
+ * hierarchy in unified, position sorted manner.
+ */
+
+/**
+ * @brief Gets next Accessible object in "structural navigation" hierarchy.
+ *
+ * @detail
+ * Gest next sibling object in accessibile objects tree which is considered as
+ * next by taking into account its position on screen. (see @position_sort for
+ * more details about visuall sorting)
+ *
+ * @param current AtspiAccessible instance from which sibling object will be
+ * searched.
+ *
+ * @retun 'Next' AtspiAccessible object pointer or NULL if not found.
+ */
 AtspiAccessible *structural_navi_same_level_next(AtspiAccessible *current);
+
+/**
+ * @brief Gets previous Accessible object in "structural navigation" hierarchy.
+ *
+ * @detail
+ * Gest previous sibling object in accessibile objects tree which is considered as
+ * previous by taking into account its position on screen. (see @position_sort for
+ * more details about visuall sorting)
+ *
+ * @param current AtspiAccessible instance from which sibling object will be
+ * searched.
+ *
+ * @retun 'Previous' AtspiAccessible object pointer or NULL if not found.
+ */
 AtspiAccessible *structural_navi_same_level_prev(AtspiAccessible *current);
 
+/**
+ * @brief Gests parent's object.
+ *
+ * @detail
+ * Gets parent object contained within same application. If there is no parent
+ * object contained in same application function should return NULL.
+ *
+ * @param object AtspiAccessible which parent will be searched.
+ * @return Parent AtspiAccessible object or NULL if not found or @current
+ * is an application object.
+ */
 AtspiAccessible *structural_navi_level_up(AtspiAccessible *current);
+
+/**
+ * @brief Gets child object.
+ *
+ * @detail
+ * Gets AtspiAccessible object considered as first child in structural
+ * navigation hierachy. Child will be sorted by its position on the screen.
+ * (see @position_sort for more details)
+ *
+ * @param object AtspiAccessible which child will be searched.
+ * @return child AtspiAccessible object or NULL if not found.
+ */
 AtspiAccessible *structural_navi_level_down(AtspiAccessible *current);
 
+/**
+ * @brief Gets next object.
+ *
+ * @detail
+ * Get next AtspiAccessible object from Atspi realation FLOWS_TO.
+ *
+ * @param object AtspiAccessible
+ * @return next AtspiAccessible object or NULL if not found.
+ */
 AtspiAccessible *structural_navi_app_chain_next(AtspiAccessible *current);
+
+/**
+ * @brief Gets previous object.
+ *
+ * @detail
+ * Get previous AtspiAccessible object from Atspi realation FLOWS_FROM.
+ *
+ * @param object AtspiAccessible
+ * @return next AtspiAccessible object or NULL if not found.
+ */
 AtspiAccessible *structural_navi_app_chain_prev(AtspiAccessible *current);
 
-#endif /* end of include guard: STRUCTURAL_NAVI_KML0ETIJ */
+#endif /* end of include guard: STRUCTURAL_NAVI_H_ */