From: Yunhee Seo <yuni.seo@samsung.com>
Date: Wed, 2 Oct 2024 07:03:11 +0000 (+0900)
Subject: touchscreen: Enhance API description
X-Git-Tag: accepted/tizen/9.0/unified/20241030.231607^0
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fheads%2Faccepted%2Ftizen_unified;p=platform%2Fcore%2Fapi%2Fdevice.git

touchscreen: Enhance API description

To improve readability and facilitate comprehension,
more detailed API descriptions are added.

Change-Id: Iffbc72a31817dff1d0964c33fea027294b9bc594
Signed-off-by: Yunhee Seo <yuni.seo@samsung.com>
---

diff --git a/include/touchscreen-internal.h b/include/touchscreen-internal.h
index 2e47139..1cea068 100644
--- a/include/touchscreen-internal.h
+++ b/include/touchscreen-internal.h
@@ -1,10 +1,120 @@
+/*
+ * Copyright (c) 2020 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_SYSTEM_TOUCHSCREEN_INTERNAL_H__
 #define __TIZEN_SYSTEM_TOUCHSCREEN_INTERNAL_H__
 
 #include <gio/gio.h>
 #include <libsyscommon/libgdbus.h>
 
+/**
+ * @brief Enables the current device's touchscreen device to start.
+ * @details Enables the touchscreen device and registers a callback function to be invoked when the operation is completed asynchronously.
+ * @since_tizen 6.0
+ * @remarks Ensure the callback @a cb signature is the as described below.
+ * @param[in] cb The callback function to be called when the operation is completed.
+ *               The callback function should have the following signature:
+ *               void callback(GVariant *result, void *data, GError *err);
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #DEVICE_ERROR_NONE Successful
+ * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * #include <device/touchscreen-internal.h>
+ * ...
+ * void dbus_cb(GVariant *result, void *data, GError *err)
+ * {
+ *     int temp = 0;
+ * 
+ *     if (!result) {
+ *         _E("Can't get result of touchscreen enable request.:%s", err->message);
+ *         return;
+ *     }
+ *     if (!g_variant_get_safe(result, "(i)", &temp)) {
+ *         _E("Failed to get variant(%s): no call back message", g_variant_get_type_string(result));
+ *         goto out;
+ *     }
+ *     _I("replay message(%d)", temp);
+ * out:
+ *     g_variant_unref(result);
+ * }
+ * ...
+ * int main(void)
+ * {
+ *     int ret = 0;
+ *
+ *     ret = device_touchscreen_enable(dbus_cb);
+ *     ...
+ *     return 0;
+ * }
+ * ...
+ * @endcode
+ * @see device_touchscreen_disable()
+ */
 int device_touchscreen_enable(dbus_pending_cb cb);
+
+/**
+ * @brief Disables the current device's touchscreen device to stop.
+ * @details Disables the touchscreen device and registers a callback function to be invoked when the operation is completed asynchronously.
+ * @since_tizen 6.0
+ * @remarks Ensure the callback @a cb signature is the as described below.
+ * @param[in] cb The callback function to be called when the operation is completed.
+ *               The callback function should have the following signature:
+ *               void callback(GVariant *result, void *data, GError *err);
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #DEVICE_ERROR_NONE Successful
+ * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * #include <device/touchscreen-internal.h>
+ * ...
+ * void dbus_cb(GVariant *result, void *data, GError *err)
+ * {
+ *     int temp = 0;
+ * 
+ *     if (!result) {
+ *         _E("Can't get result of touchscreen device api request.:%s", err->message);
+ *         return;
+ *     }
+ *     if (!g_variant_get_safe(result, "(i)", &temp)) {
+ *         _E("Failed to get variant(%s): no call back message", g_variant_get_type_string(result));
+ *         goto out;
+ *     }
+ *     _I("replay message(%d)", temp);
+ * out:
+ *     g_variant_unref(result);
+ * }
+ * ...
+ * int main(void)
+ * {
+ *     int ret = 0;
+ *
+ *     ret = device_touchscreen_enable(dbus_cb);
+ *     if (ret == DEVICE_ERROR_NONE) {
+ *         ...
+ *         ret = device_touchscreen_disable(dbus_cb);
+ *     }
+ *     return 0;
+ * }
+ * ...
+ * @endcode
+ * @see device_touchscreen_enable()
+ */
 int device_touchscreen_disable(dbus_pending_cb cb);
 
 #endif