updated interface

Author: guillaumemichel

reprovider/interface.md

@@ -3,18 +3,32 @@
 ## Suggested `SweepingReprovider` interface
 
 ```go
-type Provider interface {
-  // StartProviding provides the given keys to the DHT swarm unless they were
-  // already provided in the past. The keys will be periodically reprovided until
-  // StopProviding is called for the same keys or user defined garbage collection
-  // deletes the keys.
-  StartProviding(...mh.Multihash)
-
-  // ForceStartProviding is similar to StartProviding, but it sends provider
-  // records out to the DHT regardless of whether the keys were already provided
-  // in the past. It keeps reproviding the keys until StopProviding is called
-  // for these keys.
-  ForceStartProviding(context.Context, ...mh.Multihash) error
+// DHTProvider is an interface for providing keys to a DHT swarm. It holds a
+// state of keys to be advertised, and is responsible for periodically
+// publishing provider records for these keys to the DHT swarm before the
+// records expire.
+type DHTProvider interface {
+  // StartProviding ensures keys are periodically advertised to the DHT swarm.
+  //
+  // If the keys aren't currently being reprovided, they are immediately
+  // provided to the DHT swarm, and scheduled to be reprovided periodically. If
+  // `force` is set to true, all keys are immediately provided to the DHT
+  // swarm, regardless of whether they were already being provided in the past.
+  // `keys` keep being reprovided until `StopProviding` is called.
+  //
+  // This call blocks until the initial provide completes (or fails), at
+  // which point it returns any error related to the initial provide.
+  //
+  // Cancelling the context cancels only the immediate provide, but not the
+  // reproviding of keys which is still done at some point the future. Call
+  // `StopProviding` to stop reproviding the specified keys.
+  StartProviding(ctx context.Context, force bool, keys ...mh.Multihash) error
+
+  // StartProvidingAsync is similar to `StartProviding`, but it does not block
+  // until the initial provide operation completes or fails. The supplied keys
+  // will eventually be provided and reprovided to the DHT swarm until
+  // `StopProviding` is called.
+  StartProvidingAsync(force bool, keys ...mh.Multihash)
 
   // StopProviding stops reproviding the given keys to the DHT swarm. The node
   // stops being referred as a provider when the provider records in the DHT
@@ -23,6 +37,8 @@ type Provider interface {
 
   // ProvideOnce sends provider records for the specified keys to the DHT swarm
   // only once. It does not automatically reprovide those keys afterward.
+  //
+  // Canceling the context cancels the immediate provide of the keys.
   ProvideOnce(context.Context, ...mh.Multihash) error
 }
 ```