comments: inline clarifications (#77)

Signed-off-by: Jose Nino <jnino@lyft.com>

Description: inline comment pass prior to release. This is my pass at #37.
Signed-off-by: JP Simard <jp@jpsim.com>

mobile/.bazelrc

@@ -14,6 +14,10 @@ build \
   --xcode_version=10.2.1 \
   --incompatible_bzl_disallow_load_after_statement=false
 
+# Manual Stamping is necessary in order to get versioning information in the ios
+# static framework.
+# More information on stamping can be found here:
+# https://github.com/envoyproxy/envoy/tree/master/bazel#enabling-optional-features
 build:ios --define=manual_stamp=manual_stamp
 
 build:android --fat_apk_cpu=x86,x86_64,armeabi-v7a,arm64-v8a

mobile/dist/BUILD

@@ -7,6 +7,8 @@ envoy_package()
 
 # NOTE: You must first build the top-level targets //:ios_dist and //:android_dist to use the
 # artifacts referenced here.
+# You can also download the distributables referenced here from envoy-mobile's releases page:
+# https://github.com/lyft/envoy-mobile/releases
 
 aar_import(
     name = "envoy_mobile_android",

mobile/examples/common/config.yaml

@@ -1,3 +1,6 @@
+# Envoy config used by the example applications.
+# More information about Envoy's config can be found at:
+# https://www.envoyproxy.io/docs/envoy/latest/configuration/configuration
 static_resources:
   listeners:
     - address:

mobile/examples/java/hello_world/AndroidManifest.xml

@@ -3,6 +3,8 @@
           android:versionCode="1"
           android:versionName="0.1">
     <uses-permission android:name="android.permission.INTERNET"/>
+    <!-- This permission is needed in order to allow the application
+     to initiate DNS resolution via c-ares. -->
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
 
     <uses-sdk

mobile/examples/java/hello_world/MainActivity.java

@@ -38,6 +38,7 @@ protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_main);
 
+    // Load an envoy config, and run envoy on a separate thread.
     Envoy envoy = new Envoy();
     envoy.load();
     String config = null;
@@ -59,6 +60,7 @@ protected void onCreate(Bundle savedInstanceState) {
     recyclerView.addItemDecoration(dividerItemDecoration);
     thread.start();
 
+    // Run a request loop until the application exits.
     final Handler handler = new Handler(thread.getLooper());
     handler.postDelayed(new Runnable() {
       @Override
@@ -83,6 +85,7 @@ protected void onDestroy() {
 
   private Response makeRequest() throws IOException {
     URL url = new URL(ENDPOINT);
+    // Open connection to the envoy thread listening locally on port 9001.
     HttpURLConnection connection = (HttpURLConnection)url.openConnection();
     int status = connection.getResponseCode();
     if (status != 200) {

mobile/examples/java/hello_world/Response.java

@@ -1,5 +1,6 @@
 package io.envoyproxy.envoymobile.helloenvoy;
 
+// Response is a class to handle HTTP responses.
 public class Response {
   public final String title;
   public final String header;

mobile/examples/kotlin/hello_world/MainActivity.kt

@@ -30,6 +30,7 @@ class MainActivity : Activity() {
     super.onCreate(savedInstanceState)
     setContentView(R.layout.activity_main)
 
+    // Load an envoy config, and run envoy on a separate thread.
     val envoy = Envoy()
     envoy.load()
     envoy.run(baseContext, loadEnvoyConfig(baseContext, R.raw.config))
@@ -44,6 +45,7 @@ class MainActivity : Activity() {
     thread.start()
     val handler = Handler(thread.looper)
 
+    // Run a request loop until the application exits.
     handler.postDelayed(object : Runnable {
       override fun run() {
         try {
@@ -66,6 +68,7 @@ class MainActivity : Activity() {
 
   private fun makeRequest(): Response {
     val url = URL(ENDPOINT)
+    // Open connection to the envoy thread listening locally on port 9001
     val connection = url.openConnection() as HttpURLConnection
     val status = connection.responseCode
     if (status != 200) {

mobile/examples/kotlin/hello_world/Response.kt

@@ -1,3 +1,4 @@
 package io.envoyproxy.envoymobile.helloenvoykotlin
 
+// Response is a class to handle HTTP responses.
 class Response(val title: String, val header: String)

mobile/examples/objective-c/hello_world/ViewController.mm

@@ -59,6 +59,7 @@ - (void)startRequests {
 
 - (void)performRequest {
   NSURLSession* session = [NSURLSession sharedSession];
+  // Note that the request is sent to the envoy thread listening locally on port 9001.
   NSURL* url = [NSURL URLWithString:_ENDPOINT];
   NSURLRequest* request = [NSURLRequest requestWithURL:url];
   NSLog(@"Starting request to '%@'", url.path);

mobile/examples/swift/hello_world/ViewController.swift

@@ -27,6 +27,7 @@ final class ViewController: UITableViewController {
   }
 
   private func performRequest() {
+    // Note that the request is sent to the envoy thread listening locally on port 9001.
     let request = URLRequest(url: kURL)
     NSLog("Starting request to '\(kURL.path)")
     let task = URLSession.shared.dataTask(with: request) { [weak self] data, response, error in

mobile/library/common/jni_interface.cc

@@ -13,6 +13,9 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
     return -1;
   }
 
+  // c-ares jvm init is necessary in order to let c-ares perform DNS resolution in Envoy.
+  // More information can be found at:
+  // https://c-ares.haxx.se/ares_library_init_android.html
   ares_library_init_jvm(vm);
   return JNI_VERSION_1_6;
 }
@@ -27,6 +30,7 @@ extern "C" JNIEXPORT jint JNICALL
 Java_io_envoyproxy_envoymobile_Envoy_initialize(JNIEnv* env,
                                                 jobject, // this
                                                 jobject connectivity_manager) {
+  // See note above about c-ares.
   return ares_library_init_android(connectivity_manager);
 }
 

mobile/library/common/main_interface.cc

@@ -20,6 +20,12 @@ extern "C" int run_envoy(const char* config) {
   char* envoy_argv[] = {strdup("envoy"), strdup("--config-yaml"), strdup(config), nullptr};
 
   // Ensure static factory registration occurs on time.
+  // Envoy's static factory registration happens when main is run.
+  // However, when compiled as a library, there is no guarantee that such registration will happen
+  // before the names are needed.
+  // The following calls ensure that registration happens before the entities are needed.
+  // Note that as more registrations are needed, explicit initialization calls will need to be added
+  // here.
   Envoy::Extensions::HttpFilters::RouterFilter::forceRegisterRouterFilterConfig();
   Envoy::Extensions::NetworkFilters::HttpConnectionManager::
       forceRegisterHttpConnectionManagerFilterConfigFactory();
@@ -31,6 +37,9 @@ extern "C" int run_envoy(const char* config) {
   // Initialize the server's main context under a try/catch loop and simply
   // return EXIT_FAILURE as needed. Whatever code in the initialization path
   // that fails is expected to log an error message so the user can diagnose.
+  // Note that in the Android examples logging will not be seen.
+  // This is a known problem, and will be addressed by:
+  // https://github.com/lyft/envoy-mobile/issues/34
   try {
     main_common = std::make_unique<Envoy::MainCommon>(3, envoy_argv);
   } catch (const Envoy::NoServingException& e) {

mobile/library/java/io/envoyproxy/envoymobile/Envoy.java

@@ -6,6 +6,7 @@
 
 import java.io.*;
 
+// Wrapper class that allows for easy calling of Envoy's JNI interface in native Java.
 public class Envoy {
 
   public void load() { System.loadLibrary("envoy_jni"); }