From 77b266ed7f3e6f7a7e73334163a0341b55599b04 Mon Sep 17 00:00:00 2001 From: jomui Date: Fri, 20 Jan 2017 15:22:52 +0900 Subject: [PATCH] apply doxygen from DXL Signed-off-by: jomui Change-Id: Ic6116cec260c9ee345e821a0dfd17359cdad9aec --- include/location_bounds.h | 7 +++-- include/locations.h | 78 ++++++++++++++++++++++++++++------------------- 2 files changed, 50 insertions(+), 35 deletions(-) diff --git a/include/location_bounds.h b/include/location_bounds.h index 6d2c665..8d0248f 100644 --- a/include/location_bounds.h +++ b/include/location_bounds.h @@ -24,7 +24,8 @@ extern "C" { #endif -#define LOCATION_BOUNDS_ERROR_CLASS TIZEN_ERROR_LOCATION_MANAGER | 0x20 +#define LOCATION_BOUNDS_ERROR_CLASS TIZEN_ERROR_LOCATION_MANAGER | 0x20 + /** * @addtogroup CAPI_LOCATION_BOUNDS_MODULE @@ -100,7 +101,7 @@ typedef bool (*polygon_coords_cb)(location_coords_s coords, void *user_data); * @brief Called when the given boundary is entered or exited. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * @param[in] state The boundary state - * @pre location_manager_start() will invoke this callback if you register this callback using location_bounds_set_state_changed_cb() + * @pre location_manager_start() will invoke this callback if you register this callback using location_bounds_set_state_changed_cb(). * @see #location_boundary_state_e * @see location_manager_start() * @see location_bounds_set_state_changed_cb() @@ -282,7 +283,7 @@ int location_bounds_destroy(location_bounds_h bounds); * @retval #LOCATION_BOUNDS_ERROR_NONE Successful * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported - * @post location_bounds_state_changed_cb() will be invoked + * @post location_bounds_state_changed_cb() will be invoked. * @see location_bounds_unset_state_changed_cb() * @see location_bounds_state_changed_cb() */ diff --git a/include/locations.h b/include/locations.h index f8182ae..a619fd1 100755 --- a/include/locations.h +++ b/include/locations.h @@ -27,6 +27,7 @@ extern "C" { #endif + /** * @addtogroup CAPI_LOCATION_MANAGER_MODULE * @{ @@ -115,6 +116,8 @@ typedef struct location_manager_s *location_manager_h; /* * Location Manager */ + + /** * @addtogroup CAPI_LOCATION_MANAGER_MODULE * @{ @@ -271,7 +274,7 @@ typedef void(*location_batch_cb)(int num_of_location, void *user_data); * @param[in] user_data The user data passed from the callback registration function * @return @c true to continue with the next iteration of the loop, * otherwise @c false to break out of the loop - * @pre location_manager_foreach_location_batch() will invoke this callback + * @pre location_manager_foreach_location_batch() will invoke this callback. * @see location_manager_foreach_location_batch() */ typedef bool(*location_batch_get_location_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal, double vertical, time_t timestamp, void *user_data); @@ -365,18 +368,18 @@ int location_manager_destroy(location_manager_h manager); /** * @brief Requests to update current location once. - * @remarks Do not request to start the location service using the same manager handler - * Calling this function invokes a location service event. - * When the location service is updated, location_updated_cb * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * @privlevel public * @privilege %http://tizen.org/privilege/location + * @remarks Do not request to start the location service using the same manager handler. + * Calling this function invokes a location service event. When the location service is updated, location_updated_cb. * @param[in] manager The location manager handle * @param[in] timeout Timeout to stop requesting single location after * @param[in] callback The location callback function to register * @param[in] user_data The user data to be passed to the callback function * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled @@ -635,7 +638,7 @@ int location_manager_get_accuracy(location_manager_h manager, location_accuracy_ * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @pre The location manager handle must be created by location_manager_create() + * @pre The location manager handle must be created by location_manager_create(). */ int location_manager_get_last_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp); @@ -737,7 +740,7 @@ int location_manager_get_accessibility_state(location_accessibility_state_e *sta * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @post location_position_updated_cb() will be invoked + * @post location_position_updated_cb() will be invoked. * @see location_manager_unset_position_updated_cb() * @see location_position_updated_cb() */ @@ -770,7 +773,7 @@ int location_manager_unset_position_updated_cb(location_manager_h manager); * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @post location_velocity_updated_cb() will be invoked + * @post location_velocity_updated_cb() will be invoked. * @see location_manager_unset_velocity_updated_cb() * @see location_velocity_updated_cb() */ @@ -802,7 +805,7 @@ int location_manager_unset_velocity_updated_cb(location_manager_h manager); * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @post location_service_state_changed_cb() will be invoked + * @post location_service_state_changed_cb() will be invoked. * @see location_manager_unset_service_state_changed_cb() * @see location_service_state_changed_cb() * @see location_manager_start() @@ -838,7 +841,7 @@ int location_manager_unset_service_state_changed_cb(location_manager_h manager); * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported * @pre location_manager_add_boundary() is called before. - * @post location_zone_changed_cb() will be invoked + * @post location_zone_changed_cb() will be invoked. * @see location_manager_unset_zone_changed_cb() * @see location_zone_changed_cb() */ @@ -869,8 +872,9 @@ int location_manager_unset_zone_changed_cb(location_manager_h manager); * otherwise a negative error value * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @post location_setting_changed_cb() will be invoked + * @post location_setting_changed_cb() will be invoked. * @see location_manager_unset_setting_changed_cb() * @see location_setting_changed_cb() */ @@ -885,6 +889,7 @@ int location_manager_set_setting_changed_cb(location_method_e method, location_s * otherwise a negative error value * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported * @see location_manager_set_setting_changed_cb() */ @@ -921,7 +926,7 @@ int location_manager_get_distance(double start_latitude, double start_longitude, * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @post location_changed_cb() will be invoked + * @post location_changed_cb() will be invoked. * @see location_manager_unset_distance_based_location_changed_cb() * @see location_changed_cb() */ @@ -954,7 +959,7 @@ int location_manager_unset_distance_based_location_changed_cb(location_manager_h * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @post location_changed_cb() will be invoked + * @post location_changed_cb() will be invoked. * @see location_manager_unset_location_changed_cb() * @see location_changed_cb() */ @@ -979,6 +984,7 @@ int location_manager_unset_location_changed_cb(location_manager_h manager); * @brief Registers a callback function to be invoked when batch_period is expired. * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif * @remarks The batch_period should be greater than or equal to the batch_interval. + * In addition, sometimes the period may not work as you intended, the maximum permissible value for batch_period is device specific. * @param[in] manager The location manager handle * @param[in] callback The callback function to register * @param[in] batch_interval The batch sampling interval [1 ~ 255] (seconds) @@ -989,7 +995,7 @@ int location_manager_unset_location_changed_cb(location_manager_h manager); * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @post location_batch_cb() will be invoked + * @post location_batch_cb() will be invoked. * @see location_manager_start_batch() * @see location_batch_cb() * @see location_manager_unset_location_batch_cb() @@ -1067,26 +1073,28 @@ int location_manager_stop_batch(location_manager_h manager); * @privilege %http://tizen.org/privilege/location * @param[in] manager The location manager handle * @param[in] callback The iteration callback function - * @param[in] user_data The user data passed from the callback registration function + * @param[in] user_data The user data to be passed to the callback function * @return @c 0 on success, * otherwise a negative error value * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @pre location_manager_foreach_location_batch() is available after location_batch_cb() is invoked - * @post location_batch_get_location_cb() will be invoked + * @pre location_manager_foreach_location_batch() is available after location_batch_cb() is invoked. + * @post location_batch_get_location_cb() will be invoked. * @see location_manager_start_batch() * @see location_batch_cb() * @see location_batch_get_location_cb() */ int location_manager_foreach_location_batch(location_manager_h manager, location_batch_get_location_cb callback, void *user_data); + /** * @brief Checks whether the mock location is enabled. * @since_tizen 3.0 * @param[out] enabled Indicates whether the mock location is enabled - * @return 0 on success, otherwise a negative error value + * @return @c 0 on success, + * otherwise a negative error value * @retval #LOCATIONS_ERROR_NONE Successful * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported @@ -1096,12 +1104,15 @@ int location_manager_foreach_location_batch(location_manager_h manager, location */ int location_manager_is_enabled_mock_location(bool *enabled); + /** * @brief Enables mock location. + * @details The mock location is a testing function to make location API and callback deliver a mock location + * set by location_manager_set_mock_location() instead of real positioning data even in the other applications. * @since_tizen 3.0 - * @remarks You can enable the mock location when developer mode is enabled. * @privlevel public * @privilege %http://tizen.org/privilege/location + * @remarks The mock location can only be enabled if developer mode is enabled. * @param[in] enable The value to set * @return @c 0 on success, * otherwise a negative error value @@ -1109,9 +1120,9 @@ int location_manager_is_enabled_mock_location(bool *enabled); * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @see location_manager_is_enabled_method() - * @see location_manager_create() + * @see location_manager_is_enabled_mock_location() * @see location_manager_set_mock_location() + * @see location_manager_clear_mock_location() */ int location_manager_enable_mock_location(const bool enable); @@ -1137,9 +1148,9 @@ int location_manager_enable_mock_location(const bool enable); * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @see location_manager_is_enabled_method() - * @see location_manager_enable_mock_location() * @see location_manager_create() + * @see location_manager_is_enabled_mock_location() + * @see location_manager_enable_mock_location() * @see location_manager_clear_mock_location() */ int location_manager_set_mock_location(location_manager_h manager, const double latitude, const double longitude, const double altitude, const double speed, const double direction, const double accuracy); @@ -1159,9 +1170,9 @@ int location_manager_set_mock_location(location_manager_h manager, const double * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @see location_manager_is_enabled_method() - * @see location_manager_enable_mock_location() * @see location_manager_create() + * @see location_manager_is_enabled_mock_location() + * @see location_manager_enable_mock_location() * @see location_manager_set_mock_location() */ int location_manager_clear_mock_location(location_manager_h manager); @@ -1171,15 +1182,18 @@ int location_manager_clear_mock_location(location_manager_h manager); * @} */ + /* * GPS Status & Satellites */ + /** * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE * @{ */ + /** * @brief Called once for each satellite in range. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif @@ -1205,7 +1219,7 @@ typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int e * @param[out] num_of_inview The last number of satellites in view * @param[out] timestamp The last timestamp (time when measurement took place or @c 0 if valid) * @param[in] user_data The user data passed from the call registration function - * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb() + * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb(). * @see location_manager_start() * @see location_manager_set_position_updated_cb() */ @@ -1271,7 +1285,7 @@ int gps_status_get_satellite(location_manager_h manager, int *num_of_active, int * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @post gps_status_satellite_updated_cb() will be invoked + * @post gps_status_satellite_updated_cb() will be invoked. * @see gps_status_unset_satellite_updated_cb() * @see gps_status_satellite_updated_cb() * @see gps_status_get_satellite() @@ -1313,8 +1327,8 @@ int gps_status_unset_satellite_updated_cb(location_manager_h manager); * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start() - * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb() + * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start(). + * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb(). * @post It invokes gps_status_get_satellites_cb(). * @see gps_status_get_satellite() * @see gps_status_get_satellites_cb() @@ -1340,8 +1354,8 @@ int gps_status_foreach_satellites_in_view(location_manager_h manager, gps_status * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start() - * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb() + * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start(). + * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb(). * @see gps_status_foreach_satellites_in_view() */ int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp); @@ -1364,8 +1378,8 @@ int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start() - * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb() + * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start(). + * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb(). * @post It invokes gps_status_get_satellites_cb(). * @see gps_status_get_last_satellite() * @see gps_status_get_satellites_cb() -- 2.7.4