apply doxygen from DXLsubmit/tizen/20170120.062421accepted/tizen/wearable/20170120.121808accepted/tizen/tv/20170120.121748accepted/tizen/mobile/20170120.121735accepted/tizen/ivi/20170120.121823accepted/tizen/common/20170123.181832

Signed-off-by: jomui <jongmun.woo@samsung.com>
Change-Id: Ic6116cec260c9ee345e821a0dfd17359cdad9aec

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()