From: Abhimanyu Swami <abhimanyu1.s@samsung.com>
Date: Mon, 9 Dec 2024 10:17:28 +0000 (+0530)
Subject: Added documentation
X-Git-Tag: accepted/tizen/9.0/unified/20250424.162122~3
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=c86a6c607b509d4de3a63656236f9c74c66f4c6d;p=platform%2Fhal%2Fapi%2Flocation.git

Added documentation

Change-Id: Iff60e229951b11d491a80ee8dd534a2e21484421
Signed-off-by: Abhimanyu Swami <abhimanyu1.s@samsung.com>
(cherry picked from commit 0bf707c432b3529f130b9e10aad1782868eb88b7)
---

diff --git a/doc/hal_location_doc.h b/doc/hal_location_doc.h
new file mode 100644
index 0000000..b02dd73
--- /dev/null
+++ b/doc/hal_location_doc.h
@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2024 Samsung Electronics Co., Ltd All Rights Reserved
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an AS IS BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+#ifndef __TIZEN_HAL_LOCATION_DOC_H__
+#define __TIZEN_HAL_LOCATION_DOC_H__
+
+/**
+ * @file hal_location_doc.h
+ * @brief This file contains high level documentation of HAL Location.
+ */
+
+/**
+ * @defgroup HALAPI_HAL_LOCATION_MODULE Location
+ * @brief The @ref HALAPI_HAL_LOCATION_MODULE provides functions for location service.
+ *
+ * @section HALAPI_HAL_LOCATION_MODULE Required Header
+ *   \#include <hal-location.h>
+ *
+ * @section HALAPI_HAL_LOCATION_MODULE Overview
+ * The location HAL provides common abstraction interfaces to control location services and get information about location.
+ *
+ *
+ *
+ * @subsection HALAPI_HAL_LOCATION_MODULE_STATE_TRANSITIONS State Transitions
+ * <div><table class="doxtable" >
+ * <tr>
+ *    <th><b>FUNCTION</b></th>
+ *    <th><b>PRE-STATE</b></th>
+ *    <th><b>POST-STATE</b></th>
+ *    <th><b>SYNC TYPE</b></th>
+ * </tr>
+ * <tr>
+ *    <td> hal_location_get_backend() </td>
+ *    <td> N/A </td>
+ *    <td> N/A </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_location_put_backend() </td>
+ *    <td> N/A </td>
+ *    <td> N/A </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_location_init() </td>
+ *    <td> N/A </td>
+ *    <td> INITIALIZED </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_location_deinit() </td>
+ *    <td> INITIALIZED </td>
+ *    <td> N/A </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_location_request() </td>
+ *    <td> INITIALIZED </td>
+ *    <td> INITIALIZED </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * </table></div>
+ *
+ */
+
+#endif /* __TIZEN_HAL_LOCATION_DOC_H__ */
diff --git a/include/hal-location.h b/include/hal-location.h
index 43a2a07..ec05c09 100644
--- a/include/hal-location.h
+++ b/include/hal-location.h
@@ -25,11 +25,56 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Get the backend data of location
+ * @since HAL_MODULE_LOCATION 1.0
+ * @return @c 0 on success, otherwise a negative value
+ * @retval #-ENOSUP Invalid operation
+ * @retval #-ENOMEM Out of memory
+ * @see hal_location_put_backend()
+ */
 int hal_location_get_backend(void);
+
+/**
+ * @brief Put the backend data of location
+ * @since HAL_MODULE_LOCATION 1.0
+ * @return @c 0 on success, otherwise a negative value
+ * @retval #-EINVAL Invalid parameter
+ * @see hal_location_put_backend()
+ */
 int hal_location_put_backend(void);
 
+/**
+ * @brief Initializes new handle of location HAL.
+ * @since HAL_MODULE_LOCATION 1.0
+ * @param[in]  gps_event_cb GPS event callback fuction
+ * @param[in] user_data The user data for callback
+ * @return @c 1 on success, otherwise in case of an error
+ * @retval #-ENOSUP Invalid operation
+ * @see hal_location_deinit()
+ */
 int hal_location_init(gps_event_cb gps_event_cb, void *user_data);
+
+/**
+ * @brief Deinitializes handle of location HAL.
+ * @since HAL_MODULE_LOCATION 1.0
+ * @param[out]  reason_code Falure reason code
+ * @return @c 1 on success, otherwise in case of an error
+ * @retval #-ENOSUP Invalid operation
+ * @see hal_location_init()
+ */
 int hal_location_deinit(gps_failure_reason_t *reason_code);
+
+/**
+ * @brief Request gpa action with action data.
+ * @since HAL_MODULE_LOCATION 1.0
+ * @param[in]  gps_action The gps action to be sent to server
+ * @param[in] gps_action_data The gps action data to be sent to server
+ * @param[out]  reason_code Falure reason code
+ * @return @c 1 on success, otherwise in case of an error
+ * @retval #-ENOSUP Invalid operation
+ * @see hal_location_init()
+ */
 int hal_location_request(gps_action_t gps_action, void *gps_action_data, gps_failure_reason_t *reason_code);
 
 #ifdef __cplusplus