Add interface documentation through comments

Change-Id: I0d6c769ccb22ff0465a6518533fd5710ae1c3447
Reviewed-on: https://weave-review.googlesource.com/1402
Reviewed-by: Alex Vakulenko <avakulenko@google.com>

libweave/include/weave/provider/config_store.h

diff --git a/libweave/include/weave/provider/config_store.h b/libweave/include/weave/provider/config_store.h
index 4107748..53c1128 100644
--- a/libweave/include/weave/provider/config_store.h
+++ b/libweave/include/weave/provider/config_store.h
@@ -18,6 +18,45 @@
 namespace weave {
 namespace provider {
 
+// This interface should be implemented by the user of libweave and
+// provided during device creation in Device::Create(...)
+// libweave will use this interface to get default settings and load / save
+// settings to a persistent storage.
+//
+// Implementation of the LoadDefaults(...) method may load settings from
+// a file or just hardcode defaults for this device.
+// For example:
+//   bool FileConfigStore::LoadDefaults(Settings* settings) {
+//     settings->name = "My device";
+//     settings->pairing_modes.insert(kPinCode);
+//     // set all other required settings, see include/weave/settings.h
+//     return true;
+//   }
+//
+// Implementation of LoadSettings() method should load previously
+// stored settings from the persistent storage (file, flash, etc).
+// For example:
+//   std::string FileConfigStore::LoadSettings() {
+//     std::ifstream str("/var/lib/weave/weave_settings.json");
+//     return std::string(std::istreambuf_iterator<char>(str),
+//                        std::istreambuf_iterator<char>());
+//   }
+// If data stored encrypted (highly recommended), LoadSettings()
+// implementation should decrypt the data before returning it to libweave.
+//
+// Implementation of SaveSettings(...) method should store data in the
+// persistent storage (file, flash, etc).
+// For example:
+//   void FileConfigStore::SaveSettings(const std::string& settings) {
+//     std::ofstream str(kSettingsPath);
+//     str << settings;
+//   }
+// It is highly recommended to protected data using encryption with
+// hardware backed key.
+//
+// See libweave/examples/provider/file_config_store.cc for a complete
+// example.
+
 // Interface with methods to read/write libweave settings, device state and
 // commands definitions.
 class ConfigStore {
@@ -26,7 +65,7 @@
   // a factory reset.
   virtual bool LoadDefaults(Settings* settings) = 0;
 
-  // Returns settings saved by SaveSettings during last run of libWeave.
+  // Returns settings saved by SaveSettings during last run of libweave.
   // Implementation should return data as-is without parsing or modifications.
   virtual std::string LoadSettings() = 0;
 

libweave/include/weave/provider/dns_service_discovery.h

diff --git a/libweave/include/weave/provider/dns_service_discovery.h b/libweave/include/weave/provider/dns_service_discovery.h
index d96e22d..fa9d50e 100644
--- a/libweave/include/weave/provider/dns_service_discovery.h
+++ b/libweave/include/weave/provider/dns_service_discovery.h
@@ -13,6 +13,73 @@
 namespace weave {
 namespace provider {
 
+// This interface should be implemented by the user of libweave and
+// provided during device creation in Device::Create(...)
+// libweave will use this interface to start/stop mDNS service discovery.
+//
+// Implementation of the PublishService(...) method should publish mDNS
+// service. Publishing service should be done according to RFC 6762 (mDNS)
+// and RFC 6763 (DNS Service discovery).
+//
+// service_type will contain name of the service before .local.
+//   For example, "_privet._tcp".
+// port will have a port number where Weave HTTP server is running.
+//   For example, 80.
+// txt will contain a list of strings for mDNS TXT records.
+//   For example, "txtver=3", "name=MyDevice"
+//
+// The following mDNS records should be published in the above examples:
+// _privet._tcp.local PTR <service_name>._privet._tcp.local
+// <service_name>._privet._tcp.local SRV <local_domain> 80
+// <service_name>._privet._tcp.local TXT "txtver=3" "name=MyDevice"
+// <local_domain> A <IPv4 address>
+// <local_domain> AAAA <IPv6 address>
+//
+// In the list above, it is implementer's responsibility to choose
+// <service_name> and <local_domain>.
+// If device only supports IPv4 or IPv6, then only the corresponding mDNS
+// records should be published. <IPv4 address> and <IPv6 address> should
+// be the addresses of the network interface this record is advertised on.
+//
+// Implementation of PublishService(...) may use existing libraries or
+// services to implement mDNS service discovery. For example, Avahi or
+// Bonjour. Such implementation may require IPC or similar async
+// communication mechanisms. PublishService(...) implementation may
+// just start the process and return quickly (non-blocking) while the
+// full mDNS implementation is started in the background. In such case
+// PublishService(...) implementation should remember all input parameters
+// so it can restart service publishing in case of failures.
+// From libweave perspective, discovery is started after
+// PublishService(...) returns and libweave may not call this method again.
+//
+// Implementation of the StopPublishing(...) method should stop advertising
+// specified service type on the mDNS. This should be done according to mDNS
+// (RFC 6762) and DNS-SD (RFC 6763) specifications, which require announcing
+// DNS records that will be going away with TTL=1.
+//
+// Since this interface allows multiple service types to be published, proper
+// implementation should maintain list of service types and stop advertising
+// only the type specified in this request. Other service types, as well as
+// records necessary for other services, like A, AAAA may still be available
+// over mDNS.
+//
+// In case a device has multiple networking interfaces, the device developer
+// needs to make a decision where mDNS advertising is necessary and where it is
+// not. For example, there should be no mDNS advertising on cellular (LTE) or
+// WAN (for routers) network interfaces. In some cases, there might be more
+// then one network interface where advertising makes sense. For example,
+// a device may have both WiFi and Ethernet connections. In such case,
+// PublishService(...) should make service available on both interface.
+//
+// From libweave perspective, it always looks like there is only one network
+// interface (for both service discovery and web server). It is
+// the job of this interface implementation to hide network complexity from
+// the libweave and to bring webserver up on the same port on both interfaces,
+// as well as publish an mDNS service (uses webserver port).
+//
+// See libweave/examples/provider/avahi_client.cc for complete example
+// using Avahi for DNS service discovery.
+
 class DnsServiceDiscovery {
  public:
   // Publishes new service using DNS-SD or updates existing one.

libweave/include/weave/provider/http_client.h

diff --git a/libweave/include/weave/provider/http_client.h b/libweave/include/weave/provider/http_client.h
index 6edf4bf..deb127a 100644
--- a/libweave/include/weave/provider/http_client.h
+++ b/libweave/include/weave/provider/http_client.h
@@ -15,6 +15,54 @@
 namespace weave {
 namespace provider {
 
+// This interface should be implemented by the user of libweave and
+// provided during device creation in Device::Create(...)
+// libweave will use this interface to make HTTP/HTTPS calls to external
+// services.
+//
+// HttpClient interface has only one method SendRequest(...) to implement.
+// However, user code should also implement Response interface, that will be
+// passed into callback.
+//
+// Implementation of the SendRequest(...) method should make a proper
+// HTTP / HTTPS call according to the input parameters:
+//   method - of the supported methods (kGet, kPatch, kPost, kPut) which
+//     should map to the corresponding HTTP verb (GET, PATCH, POST, PUT) in
+//     the request.
+//   url - full URL including protocol, domain, path and parameters. Protocol
+//     may be "http" or "https". In case of "https", it is implementer's
+//     responsibility to establish a secure connection and verify endpoint
+//     certificate chain. libweave will attempt connecting to Google Weave
+//     servers. Proper root CA certificates should be available on the device.
+//   headers - list of HTTP request headers that should be attached to the
+//     request.
+//   data - binary data that should be sent within HTTP request body. Empty
+//     string means no data. Implementation needs to check for that. For
+//     example, kGet method should never have data. It is also possible to have
+//     no data for other methods as well.
+//   callback - standard callback to notify libweave when request is complete
+//     and provide results and response data.
+//
+// Implementation of the SendRequest(...) should be non-blocking, meaning it
+// should schedule network request and return right away. Later (after the
+// request is complete), callback should be invokes on the same thread.
+// Callback should never be called before SendRequest(...) returns.
+//
+// When invoking callback function, user should privide implementation
+// of the Response interface. For example, the following could be used as a
+// simple implementation:
+//   struct ResponseImpl : public provider::HttpClient::Response {
+//     int GetStatusCode() const override { return status; }
+//     std::string GetContentType() const override { return content_type; }
+//     std::string GetData() const override { return data; }
+//     int status{0};
+//     std::string content_type;
+//     std::string data;
+//   };
+//
+// See libweave/examples/provider/curl_http_client.cc for complete example
+// implementing HttpClient interface using curl.
+
 class HttpClient {
  public:
   enum class Method {