From 3e275221e296650b501730fdb75951c19599f22f Mon Sep 17 00:00:00 2001 From: Minkyoung Kang Date: Fri, 29 Mar 2013 11:15:22 +0900 Subject: update the header for Doxygen Change-Id: Icd13ebae99726f98ab1d870d796cd0fee34b0e19 --- inc/FLocCoordinates.h | 38 +++++--------- inc/FLocILocationProviderListener.h | 66 +++++++++-------------- inc/FLocLocationCriteria.h | 3 +- inc/FLocLocationProvider.h | 101 +++++++++++++++--------------------- 4 files changed, 81 insertions(+), 127 deletions(-) diff --git a/inc/FLocCoordinates.h b/inc/FLocCoordinates.h index 1d1255b..186dc5e 100644 --- a/inc/FLocCoordinates.h +++ b/inc/FLocCoordinates.h @@ -56,8 +56,7 @@ class _OSP_EXPORT_ Coordinates { public: /** - * Initializes an instance of %Coordinates with the values of latitude, longitude, and altitude to Not-a-Number. - * + * Initializes an instance of %Coordinates with the values of latitude, longitude, and altitude to Not-a-Number. @n * An application should set values of the coordinates using Set() method to specify it. * * @since 2.0 @@ -101,9 +100,8 @@ public: virtual int GetHashCode(void) const; /** - * Sets the latitude, longitude, and altitude values of the coordinates. - * - * An application should specify latitude and longitude values in the valid ranges of [-90.0, +90.0] and [-180.0, +180.0], respectively. + * Sets the latitude, longitude, and altitude values of the coordinates. @n + * An application should specify latitude and longitude values in the valid ranges of [-90.0, +90.0] and [-180.0, +180.0], respectively. @n * Otherwise, the %Set() method returns an @c E_INVALID_ARG exception. * * @since 2.0 @@ -121,9 +119,8 @@ public: result Set(double latitude, double longitude, double altitude); /** - * Sets the latitude value of the coordinates. - * - * An application should specify latitude value in the valid range of [-90.0, +90.0]. + * Sets the latitude value of the coordinates. @n + * An application should specify latitude value in the valid range of [-90.0, +90.0]. @n * Otherwise, the %SetLatitude() method returns an @c E_INVALID_ARG exception. * * @since 2.0 @@ -137,9 +134,8 @@ public: result SetLatitude(double latitude); /** - * Sets the longitude value of the coordinates. - * - * An application should specify longitude value in the valid range of [-180.0, +180.0]. + * Sets the longitude value of the coordinates. @n + * An application should specify longitude value in the valid range of [-180.0, +180.0]. @n * Otherwise, the %SetLongitude() method returns an @c E_INVALID_ARG exception. * * @since 2.0 @@ -196,11 +192,9 @@ public: double GetAltitude(void) const; /** - * Calculates the azimuth value. - * - * The coordinates are the starting point and @c dest is the destination for the azimuth calculation. - * The azimuth is measured clockwise from true north based on the WGS84 ellipsoid model. - * + * Calculates the azimuth value. @n + * The coordinates are the starting point and @c dest is the destination for the azimuth calculation. @n + * The azimuth is measured clockwise from true north based on the WGS84 ellipsoid model. @n * The altitude value is not considered in calculation. * * @since 2.0 @@ -212,10 +206,8 @@ public: double GetAzimuth(const Coordinates& dest) const; /** - * Calculates the geodetic distance for the given coordinates. - * - * The distance calculation is based on the WGS84 ellipsoid model. - * + * Calculates the geodetic distance for the given coordinates. @n + * The distance calculation is based on the WGS84 ellipsoid model. @n * The altitude value is not considered in calculation. * * @since 2.0 @@ -227,8 +219,7 @@ public: double GetDistanceTo(const Coordinates& to) const; /** - * Converts the coordinate value into string. - * + * Converts the coordinate value into string. @n * An application specifies formats like @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND for the result string. * * @since 2.0 @@ -244,8 +235,7 @@ public: static result ToString(double degree, CoordinateFormat format, Tizen::Base::String& string); /** - * Converts a string into coordinate degree. - * + * Converts a string into coordinate degree. @n * The @c string should be in @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND format. * * @since 2.0 diff --git a/inc/FLocILocationProviderListener.h b/inc/FLocILocationProviderListener.h index 44b03b9..7435190 100644 --- a/inc/FLocILocationProviderListener.h +++ b/inc/FLocILocationProviderListener.h @@ -50,7 +50,7 @@ class _OSP_EXPORT_ ILocationProviderListener { public: /** - * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called + * This polymorphic destructor should be overridden if required. @n This way, the destructors of the derived classes are called * when the destructor of this interface is called. * * @since 2.0 @@ -58,14 +58,11 @@ public: virtual ~ILocationProviderListener(void) {} /** - * Called when the location update is running. - * - * The location update is started when an application calls the LocationProvider::StartLocationUpdatesByInterval() or LocationProvider::StartLocationUpdatesByDistance() methods. - * - * Note that, the updated locations may not always fall into the requested accuracy level that the application has specified in the criteria. + * Called when the location update is running. @n + * The location update is started when an application calls the LocationProvider::StartLocationUpdatesByInterval() or LocationProvider::StartLocationUpdatesByDistance() methods. @n + * Note that, the updated locations may not always fall into the requested accuracy level that the application has specified in the criteria. @n * The application is able to filter out less accurate locations by checking the location accuracy with the Location::GetHorizontalAccuracy() method - * if it matters to the application. - * + * if it matters to the application. @n * During updating locations, along with changes in the location's accuracy, changes in the service status are also notified. * * @since 2.0 @@ -78,10 +75,8 @@ public: virtual void OnLocationUpdated(const Tizen::Locations::Location& location) { } /** - * Called when the location provider detects a movement entering into the registered region. - * - * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and is identified by the region ID. - * + * Called when the location provider detects a movement entering into the registered region. @n + * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and is identified by the region ID. @n * While monitoring regions, the changes in the location's accuracy and the changes in the service status are notified. * * @since 2.0 @@ -94,10 +89,8 @@ public: virtual void OnRegionEntered(Tizen::Locations::RegionId regionId) { } /** - * Called when the location provider detects a movement leaving from the registered region. - * - * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and identified by the region ID. - * + * Called when the location provider detects a movement leaving from the registered region. @n + * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and identified by the region ID. @n * While monitoring regions, the changes in the location's accuracy and the changes in the service status are notified. * * @since 2.0 @@ -110,22 +103,17 @@ public: virtual void OnRegionLeft(Tizen::Locations::RegionId regionId) { } /** - * Called when the service status of the location updates change. - * - * The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service. - * + * Called when the service status of the location updates change. @n + * The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service. @n * The status changes to @c LOC_SVC_STATUS_NOT_FIXED, when the location provider is not able to run the requested service because it - * cannot fix the current location due to poor circumstances such as weak radio for positioning. - * When this status continues for a fairly long time, it is recommended to cancel the request. The request should be run after some time in order to avoid excessive battery consumption. - * + * cannot fix the current location due to poor circumstances such as weak radio for positioning. @n + * When this status continues for a fairly long time, it is recommended to cancel the request. The request should be run after some time in order to avoid excessive battery consumption. @n * When the user withdraws the permission for an application to use the location information, the status changes to - * @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application. + * @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application. @n * In that case, the application might ask the user to grant permission to continue the aborted service - * or to finalize all resources for the location provider. - * + * or to finalize all resources for the location provider. @n * The status @c LOC_SVC_STATUS_PAUSED is displayed when the location provider pauses the ongoing service. This happens when the application requests for the location updates without keeping the location updates awake. The status will be changed to others - * once the location provider resumes the paused service. - * + * once the location provider resumes the paused service. @n * Note that, the application can get notifications about the location updates and accuracy changes * only when the service status is @c LOC_SVC_STATUS_RUNNING. * @@ -138,18 +126,14 @@ public: /** - * Called when the service status of the region monitoring changes. - * - * The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service. - * + * Called when the service status of the region monitoring changes. @n + * The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service. @n * The status changes to @c LOC_SVC_STATUS_NOT_FIXED, when the location provider is not able to run the requested service because it - * cannot fix the location that is suitable for monitoring the regions. - * + * cannot fix the location that is suitable for monitoring the regions. @n * When the user withdraws the permission for an application to use the location information, the status changes to - * @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application. + * @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application. @n * In that case, the application might ask the user to grant permission to continue the aborted service - * or to finalize all resources for the location provider. - * + * or to finalize all resources for the location provider. @n * Note that, the application can get notifications about the movement around regions and accuracy changes * only when the service status is @c LOC_SVC_STATUS_RUNNING. * @@ -162,12 +146,10 @@ public: /** - * Called when the accuracy level of the location changes. - * + * Called when the accuracy level of the location changes. @n * The location provider tries to provide accurate location services as specified in the criteria, - * but the location provided by location provider may not always fall into the requested accuracy level. - * The %OnAccuracyChanged() listener method is called whenever the current accuracy of the location provided by location provider is changed. - * + * but the location provided by location provider may not always fall into the requested accuracy level. @n + * The %OnAccuracyChanged() listener method is called whenever the current accuracy of the location provided by location provider is changed. @n * The accuracy changes to @c LOC_ACCURACY_INVALID when the location provider is not running any services in @c LOC_SVC_STATUS_RUNNING * status. * diff --git a/inc/FLocLocationCriteria.h b/inc/FLocLocationCriteria.h index cc62824..f9cc06d 100644 --- a/inc/FLocLocationCriteria.h +++ b/inc/FLocLocationCriteria.h @@ -64,8 +64,7 @@ public: LocationCriteria(void); /** - * This is the copy constructor for the %LocationCriteria class. - * + * This is the copy constructor for the %LocationCriteria class. @n * Copying of objects using this copy constructor is allowed. * * @since 2.0 diff --git a/inc/FLocLocationProvider.h b/inc/FLocLocationProvider.h index 22cc5a0..7adc8cb 100644 --- a/inc/FLocLocationProvider.h +++ b/inc/FLocLocationProvider.h @@ -56,7 +56,8 @@ class _OSP_EXPORT_ LocationProvider { public: /** - * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after + * The object is not fully constructed after this constructor is called. @n + * For full construction, the Construct() method must be called right after * calling this constructor. * * @since 2.0 @@ -71,12 +72,10 @@ public: virtual ~LocationProvider(void); /** - * Initializes this instance of %LocationProvider with the specified @c criteria and @c listener. - * + * Initializes this instance of %LocationProvider with the specified @c criteria and @c listener. @n * An application chooses the desired service quality based on its scenario and constructs the location provider with the specified - * @c criteria. The desired accuracy for locations is a configurable property of LocationCriteria. - * The location provider tries to provides locations and services based on the specified @c criteria. - * + * @c criteria. The desired accuracy for locations is a configurable property of LocationCriteria. @n + * The location provider tries to provides locations and services based on the specified @c criteria. @n * The @c listener is notified on asynchronous location updates or region monitoring events. * * @since 2.0 @@ -94,26 +93,23 @@ public: result Construct(const LocationCriteria& criteria, ILocationProviderListener& listener); /** - * Requests the location updates service with the specific @c interval. - * + * Requests the location updates service with the specific @c interval. @n * Once the location updates have started and the location provider has fixed the current location, the location is delivered - * to the listener by calling the ILocationProviderListener::OnLocationUpdated() method. + * to the listener by calling the ILocationProviderListener::OnLocationUpdated() method. @n * The location provider is trying to provide accurate locations as requested in the criteria, but locations updated by the location provider * do not always fall into the requested accuracy level. It provides locations in low-grade accuracy if that is all it can offer - * or can not even provide locations when it hardly fixes the current location. The location provider notifies the listener whenever the accuracy - * level of ongoing updates are changed by calling the ILocationProviderListener::OnAccuracyChanged() method. - * + * or can not even provide locations when it hardly fixes the current location. @n The location provider notifies the listener whenever the accuracy + * level of ongoing updates are changed by calling the ILocationProviderListener::OnAccuracyChanged() method. @n * The location updates can be paused by the location provider when the application is unable to point locations out to the user - * for the moment. This is possible for the following situations: + * for the moment. @n This is possible for the following situations: * - The application is not running in foreground. * - The screen is off. - * In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener. - * It resumes the paused location updates when the application gets out of the situations. - * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method. * + * In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener. @n + * It resumes the paused location updates when the application gets out of the situations. @n + * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method. @n * The change in the service status that the location provider is providing are notified to the listener - * by calling the ILocationProviderListener::OnLocationUpdateStatusChanged() method. - * + * by calling the ILocationProviderListener::OnLocationUpdateStatusChanged() method. @n * If the location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() methods, * the location provider cancels the prior request and restarts the updates with the specified parameter. * @@ -132,24 +128,21 @@ public: result StartLocationUpdatesByInterval(int interval); /** - * Requests the location updates service with the specific @c distance filter. - * + * Requests the location updates service with the specific @c distance filter. @n * Once the location updates have started, the initial location is delivered soon after it becomes available to the listener - * by calling the ILocationProviderListener::OnLocationUpdated() method. Then the location provider updates subsequent locations - * when it changes over the specified @c distance. - * + * by calling the ILocationProviderListener::OnLocationUpdated() method. @n Then the location provider updates subsequent locations + * when it changes over the specified @c distance. @n * The location updates can be paused by the location provider when the application is unable to point locations out to the user - * for the moment. This is possible for the following situations: + * for the moment. @n This is possible for the following situations: * - The application is not running in foreground. * - The screen is off. - * In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener. - * It resumes the paused location updates when the application gets out of the situations. - * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method. * + * In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener. @n + * It resumes the paused location updates when the application gets out of the situations. @n + * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method. @n * Along with the service status, the accuracy level that the location provider is currently providing * is notified to the listener on changes by calling the ILocationProviderListener::OnLocationUpdateStatusChanged() - * and ILocationProviderListener::OnAccuracyChanged() methods respectively. - * + * and ILocationProviderListener::OnAccuracyChanged() methods respectively. @n * If the location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() methods, * the location provider cancels the prior request and restarts the updates with the specified parameter. * @@ -181,15 +174,14 @@ public: result StopLocationUpdates(void); /** - * Keeps the location updates awake or not. - * + * Keeps the location updates awake or not. @n * The location provider can pause the ongoing location updates when the application is unable to point locations out to the user - * for the moment. This is possible for the following situations: + * for the moment. @n This is possible for the following situations: * - The application is not running in foreground. * - The screen is off. * * To get the location updates all the time, the application should use the StartLocationUpdatesByInterval() or - * StartLocationUpdatesByDistance() methods together with the %KeepLocationUpdateAwake() method turning the flag @c enable on. + * StartLocationUpdatesByDistance() methods together with the %KeepLocationUpdateAwake() method turning the flag @c enable on. @n * The application should be cautious about doing so since it can make the system awake * during the location updates. * @@ -210,18 +202,15 @@ public: result KeepLocationUpdateAwake(bool enable); /** - * Adds a region for monitoring. - * - * A region is defined by a center point and a radius. + * Adds a region for monitoring. @n + * A region is defined by a center point and a radius. @n * The location provider starts the region monitoring service until all regions are removed. When it detects a movement that crosses the * boundary of a registered region, it notifies the application by calling ILocationProviderListener::OnRegionEntered() or - * ILocationProviderListener::OnRegionLeft() with the region identifier that is returned by the %AddMonitoringRegion() method. - * The altitude of @c regionCenter is not considered in monitoring. - * + * ILocationProviderListener::OnRegionLeft() with the region identifier that is returned by the %AddMonitoringRegion() method. @n + * The altitude of @c regionCenter is not considered in monitoring. @n * Along with the service status, the accuracy level that the location provider is currently providing * is notified to the listener on changes by calling the ILocationProviderListener::OnRegionMonitoringStatusChanged() - * and ILocationProviderListener::OnAccuracyChanged() methods respectively. - * + * and ILocationProviderListener::OnAccuracyChanged() methods respectively. @n * Note that, the monitoring service can sometimes makes the system awake by running costly positioning devices. * * @since 2.0 @@ -266,10 +255,9 @@ public: void RemoveAllMonitoringRegions(void); /** - * Gets the current service status of the location updates. - * + * Gets the current service status of the location updates. @n * The location updates service is started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() - * method. If an application has not made valid requests for the service, the %GetLocationUpdateStatus() method returns @c LOC_SVC_STATUS_IDLE. + * method. If an application has not made valid requests for the service, the %GetLocationUpdateStatus() method returns @c LOC_SVC_STATUS_IDLE. @n * Otherwise, it returns the service status notified last by the ILocationProviderListener::OnLocationUpdateStatusChanged() listener method. * * @since 2.0 @@ -278,10 +266,9 @@ public: LocationServiceStatus GetLocationUpdateStatus(void) const; /** - * Gets the current service status of the region monitoring. - * - * The region monitoring service is started by calling the AddMonitoringRegion() method. - * If an application has not made valid requests for the service, the %GetRegionMonitoringStatus() method returns @c LOC_SVC_STATUS_IDLE. + * Gets the current service status of the region monitoring. @n + * The region monitoring service is started by calling the AddMonitoringRegion() method. @n + * If an application has not made valid requests for the service, the %GetRegionMonitoringStatus() method returns @c LOC_SVC_STATUS_IDLE. @n * Otherwise, it returns the service status notified last by the ILocationProviderListener::OnRegionMonitoringStatusChanged() listener method. * * @since 2.0 @@ -290,10 +277,9 @@ public: LocationServiceStatus GetRegionMonitoringStatus(void) const; /** - * Gets the accuracy level that the location provider is currently providing. - * + * Gets the accuracy level that the location provider is currently providing. @n * If an application has not made valid requests for location updates and region monitoring, the %GetCurrentAccuracy() method - * returns @c LOC_ACCURACY_INVALID. + * returns @c LOC_ACCURACY_INVALID. @n * Otherwise, it returns the accuracy level last notified by the ILocationProviderListener::OnAccuracyChanged() listener method. * * @since 2.0 @@ -302,11 +288,9 @@ public: LocationAccuracy GetCurrentAccuracy(void) const; /** - * Gets a current location. - * - * An application can simply get the current location with the %GetLocation() method. - * - * The location provider runs and waits for positioning systems to fix the current location as requested in the criteria. + * Gets a current location. @n + * An application can simply get the current location with the %GetLocation() method. @n + * The location provider runs and waits for positioning systems to fix the current location as requested in the criteria. @n * If it is not fixed in some time, this method call is aborted and returns a location in low-grade accuracy or even * an invalid location with an @c E_LOCATION_UNAVAILABLE error. * @@ -332,9 +316,8 @@ public: static Location GetLocation(const LocationCriteria& criteria); /** - * Gets the last known location. - * - * The %GetLastKnownLocation() method returns the last location the system keeps. + * Gets the last known location. @n + * The %GetLastKnownLocation() method returns the last location the system keeps. @n * It is always a good idea to prefer using this method than requesting current locations * since using the last location preserves the location provider from running costly positioning systems. * -- cgit v1.2.3