Make comments easier to read
Change-Id: Ie6399e0bd18f81fd0b3b9df7bbf91764f4315ee9
diff --git a/src/com/android/telecomm/CallServiceRepository.java b/src/com/android/telecomm/CallServiceRepository.java
index 2abc8fe..40a1e7b 100644
--- a/src/com/android/telecomm/CallServiceRepository.java
+++ b/src/com/android/telecomm/CallServiceRepository.java
@@ -57,11 +57,7 @@
/** Used to run code (e.g. messages, Runnables) on the main (UI) thread. */
private final Handler mHandler = new Handler(Looper.getMainLooper());
- /**
- * Used to interrupt lookup cycles that didn't terminate naturally within the allowed
- * period, see {@link Timeouts#getProviderLookupMs()}.
- */
- private final Runnable mLookupTerminator = new Runnable() {
+ private final Runnable mTimeoutLookupTerminator = new Runnable() {
@Override
public void run() {
Log.d(CallServiceRepository.this, "Timed out processing providers");
@@ -80,22 +76,16 @@
private boolean mIsLookupInProgress = false;
/**
- * Stores the names of the providers to bind to in one lookup cycle. The set size represents
- * the number of call-service providers this repository expects to hear back from upon
- * initiating call-service lookups, see initiateLookup. Whenever all providers respond before
- * the lookup timeout occurs, the complete set of (available) call services is passed to the
- * switchboard for further processing of outgoing calls etc. When the timeout occurs before all
- * responses are received, the partial (potentially empty) set gets passed (to the switchboard)
- * instead. Entries are removed from this set as providers are processed.
+ * Stores the names of the providers to bind to in one lookup cycle. During lookup two things
+ * can happen:
+ * - lookup can succeed, in this case this set will be empty at the end of the lookup.
+ * - lookup can timeout, in this case any outstanding providers will be discarded.
*/
private final Set<ComponentName> mOutstandingProviders = Sets.newHashSet();
/**
- * The map of call-service wrappers keyed by their ComponentName. Used to ensure at most one
- * instance exists per call-service type at any given time. Populated during lookup cycles to
- * include all-known ICallService implementations (i.e. wrappers thereof) and then updated to
- * include only active call services (ones that are associated with one or more active calls)
- * upon {@link #purgeInactiveCallServices()} invocations.
+ * The map of call-service wrappers keyed by their ComponentName. This is passed back to the
+ * switchboard once lookup is complete.
*/
private final Map<ComponentName, CallServiceWrapper> mCallServices = Maps.newHashMap();
@@ -148,8 +138,8 @@
Log.i(this, "Found %d implementations of ICallServiceProvider.",
mOutstandingProviders.size());
- // Schedule a lookup terminator to run after Timeouts.getProviderLookupMs() milliseconds.
- mHandler.postDelayed(mLookupTerminator, Timeouts.getProviderLookupMs());
+ // Schedule a timeout.
+ mHandler.postDelayed(mTimeoutLookupTerminator, Timeouts.getProviderLookupMs());
}
/**
@@ -247,11 +237,9 @@
}
/**
- * Processes the {@link CallServiceDescriptor}s for the specified provider, and performs the
- * necessary bookkeeping to potentially return control to the switchboard before the timeout
- * for the current lookup cycle.
+ * Creates {@link CallServiceWrapper}s from the given {@link CallServiceDescriptor}s.
*
- * @param provider The provider associated with callServices.
+ * @param provider The provider associated with call services.
* @param callServiceDescriptors The set of call service descriptors to process.
*/
private void processCallServices(
@@ -275,16 +263,15 @@
removeOutstandingProvider(providerName);
} else {
- Log.i(this,
- "Unexpected call services from %s in lookup %s", providerName, mLookupId);
+ Log.i(this, "Unexpected call services from %s in lookup %s", providerName, mLookupId);
}
}
/**
- * Creates the call service for the specified call-service descriptor and saves newly-created
- * entries into {@link #mCallServices}. Does nothing upon already-registered entries.
+ * Creates a call-service wrapper from the given call-service descriptor if no cached instance
+ * exists.
*
- * @param descriptor The call service descriptor.
+ * @param descriptor The call-service descriptor.
*/
private void registerCallService(CallServiceDescriptor descriptor) {
Preconditions.checkNotNull(descriptor);
@@ -318,10 +305,10 @@
}
/**
- * Timeouts the current lookup cycle, see LookupTerminator.
+ * Terminates the current lookup cycle, either due to a timeout or completed lookup.
*/
private void terminateLookup() {
- mHandler.removeCallbacks(mLookupTerminator);
+ mHandler.removeCallbacks(mTimeoutLookupTerminator);
mOutstandingProviders.clear();
updateSwitchboard();
diff --git a/src/com/android/telecomm/CallServiceWrapper.java b/src/com/android/telecomm/CallServiceWrapper.java
index 807f427..a1a247a 100644
--- a/src/com/android/telecomm/CallServiceWrapper.java
+++ b/src/com/android/telecomm/CallServiceWrapper.java
@@ -32,8 +32,6 @@
* Wrapper for {@link ICallService}s, handles binding to {@link ICallService} and keeps track of
* when the object can safely be unbound. Other classes should not use {@link ICallService} directly
* and instead should use this class to invoke methods of {@link ICallService}.
- * TODO(santoscordon): Keep track of when the service can be safely unbound.
- * TODO(santoscordon): Look into combining with android.telecomm.CallService.
*/
final class CallServiceWrapper extends ServiceBinder<ICallService> {
diff --git a/src/com/android/telecomm/IncomingCallsManager.java b/src/com/android/telecomm/IncomingCallsManager.java
index 3b6365f..0493df8 100644
--- a/src/com/android/telecomm/IncomingCallsManager.java
+++ b/src/com/android/telecomm/IncomingCallsManager.java
@@ -26,10 +26,7 @@
import java.util.Map;
/**
- * Utility class to retrieve details of an incoming call after receiving an incoming-call intent,
- * see {@link CallActivity}. Binds with the specified call services and requests details of incoming
- * calls. Upon receipt of the details, yields execution back to the switchboard to complete the
- * incoming sequence. The entire process is timeboxed to protect against unresponsive call services.
+ * Used to retrieve details about an incoming call. This is invoked after an incoming call intent.
*/
final class IncomingCallsManager {
@@ -48,8 +45,7 @@
}
/**
- * Retrieves details of an incoming call through its associated call service (asynchronously).
- * Starts the timeout sequence in case the call service is unresponsive.
+ * Retrieves details of an incoming call through its associated call service.
*
* @param call The call object.
* @param extras The optional extras passed with the incoming call intent (to be returned to
diff --git a/src/com/android/telecomm/ThreadUtil.java b/src/com/android/telecomm/ThreadUtil.java
index 3d5a498..35b4c29 100644
--- a/src/com/android/telecomm/ThreadUtil.java
+++ b/src/com/android/telecomm/ThreadUtil.java
@@ -19,8 +19,7 @@
import android.os.Looper;
/**
- * A utility class which helps organize callers' threads. This class cannot be instantiated; callers
- * should use the static methods.
+ * Helper methods to deal with threading related tasks.
*/
public final class ThreadUtil {
private static final String TAG = ThreadUtil.class.getSimpleName();