Enhance API documentation

[akoshunyadi]

Problem description
From a review of @tanjadegroot :

For the novice user of this API (like me) the description is not sufficient: when do I subscribe to roaming status as opposed to roaming_on/off ? do I need to subscribe in addition to the countrychange event ? or is the roaming status event sent in case of country change ? Maybe to take up for the next release.
would be good to have a bit more explanation beyond just the list of events.

Expected action
Review and enhance the API documentation for all 4 APIs

Additional context

[sachinvodafone]

My understanding on 'roaming-change-country" is as follows:

Use Case	Required Subscriptions	Note
Notify me whenever the device changes countries while roaming	roaming-change-country	- If you want to track the country changes while the device remains in a roaming state. For example, if a device moves from France to Germany while roaming, you’ll get notified.
		- The subscription will not end automatically when a device returns to its home country. The device subscription will remain active until:
		- You explicitly unsubscribe.
		- The subscription expires (if there’s an expiration mechanism in place).
		- However, no notifications will be sent from roaming-change-country unless the device re-enters a roaming state and subsequently changes countries.
Notify me of any roaming status change and country changes	roaming-status + roaming-change-country	You need to subscribe to 2 events in this scenario.

[gmuratk]

Additional comment regarding documentation:

Based on my understanding org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected event type requires subscription as it is not explicitly stated otherwise, and scope exists for 'create'. With this understanding in mind:

• Description 'Event triggered when the device is not connected' doesn't clearly describe the behavior. If subscribed, will this event be sent every time a type of reachability (Data, SMS) is lost, or is only triggered when device is not reachable via either DATA or SMS?
• Is there an assumption that reachability-data and/or reachability-sms events are subscribed for this event type to be used.?
• What's the behavior when initialEvent=true is set for this event type? (similar discussion in Explicit initialEvent for event type org.camaraproject.roaming-status-subscriptions.v0.roaming-status  #218 ) What would be checked against the 'current situation'?

[gmuratk]

My understanding on 'roaming-change-country" is as follows:

Use Case Required Subscriptions Note
Notify me whenever the device changes countries while roaming roaming-change-country - If you want to track the country changes while the device remains in a roaming state. For example, if a device moves from France to Germany while roaming, you’ll get notified.

• The subscription will not end automatically when a device returns to its home country. The device subscription will remain active until:
• You explicitly unsubscribe.
• The subscription expires (if there’s an expiration mechanism in place).
• However, no notifications will be sent from roaming-change-country unless the device re-enters a roaming state and subsequently changes countries.
  Notify me of any roaming status change and country changes roaming-status + roaming-change-country You need to subscribe to 2 events in this scenario.

Question: What is the expected behavior if initialEvent=true set in the subscription request for roaming-change-country event type? (similar discussion in #218) What would be checked against the 'current situation'?

[sachinvodafone]

#218

In this scenario, an event will be generated only if the device is in roaming; otherwise, no event will be triggered.

[akoshunyadi]

That's a good question, because if I go from not-roaming to roaming I won't receive a roaming-change-country, right?
But if subscribe in this situation to the event with initialEvent = true, then I should receive it?
My general understanding is, that the caller should receive an event immediately on initialEvent = true, when he would have received the same event by subscribing earlier to the event.
Now in this situation we probably don't have the information whether we came from the home country or another roaming country.

[gmuratk]

In the table below, I listed the scenarios for initialEvent=true cases for all the Event Types supported in for roaming-status-subscriptions.yaml . It would be good, at least for me, to get confirmation on this

Subscribed Event Type	Current Situation to check against for initialEvent=true	Roaming Status	Immediate Response?	EventDataStructure {required properties}	Data sent back(roaming)
roaming-status	State does not matter	ON	YES	RoamingStatus {device, roaming}	TRUE
roaming-status	State does not matter	OFF	YES	RoamingStatus {device, roaming}	FALSE
roaming-on	Device is in Roaming State	ON	YES	BasicDeviceEventData {device}	N/A
roaming-on	Device is in Roaming State	OFF	NO	N/A	N/A
roaming-off	Device is NOT in Roaming State	ON	NO	N/A	N/A
roaming-off	Device is NOT in Roaming State	OFF	YES	BasicDeviceEventData {device}	N/A
roaming-change-country	Device is in Roaming State	ON	YES	RoamingChangeCountry {device}	N/A
roaming-change-country	Device is in Roaming State	OFF	NO	N/A	N/A

Please note that RoamingChangeCountry structure doesn't require country information to be included. Should it be?
I also wonder if for some event types initialEvent=true is NOT applicable, and API documentation should make it clear for implementors.