Modify NodeJS codegen to fit with gcloud-node design. (#392)

* Modify NodeJS codegen to fit with gcloud-node design.

- The new style exports a function instead of the class. The
  exported function will take the auth context as a parameter
  and returns builder function.
- Files will be under a sub directory with versioned name,
  so that it can be exposed as a sub package of the API package.
- A few misc changes and style changes made to pass lint
  checker in gcloud.

* Rebase and fix test baselines.

* Fix doc comments.

- constructor parameters are not actually useful now. They are
  parameters to the builder function actually, so I moved there.
- build() is not a function, now it's a class. This way, JSDoc
  can generate documentations for its methods (like builder function).
- add an example clause in the constructor doc comments, so that
  documentation says the details of how to create an instance of
  the API client.

* Modify comments.

src/main/java/com/google/api/codegen/gapic/MainGapicProviderFactory.java

@@ -25,6 +25,7 @@
 import com.google.api.codegen.csharp.CSharpSnippetSetRunner;
 import com.google.api.codegen.go.GoGapicContext;
 import com.google.api.codegen.go.GoSnippetSetRunner;
+import com.google.api.codegen.nodejs.NodeJSCodePathMapper;
 import com.google.api.codegen.nodejs.NodeJSGapicContext;
 import com.google.api.codegen.nodejs.NodeJSSnippetSetRunner;
 import com.google.api.codegen.py.PythonGapicContext;
@@ -140,8 +141,7 @@ public static List<GapicProvider<? extends Object>> defaultCreate(
       return Arrays.<GapicProvider<? extends Object>>asList(mainProvider, testProvider);
 
     } else if (id.equals(NODEJS)) {
-      GapicCodePathMapper nodeJSPathMapper =
-          CommonGapicCodePathMapper.newBuilder().setPrefix("src").build();
+      GapicCodePathMapper nodeJSPathMapper = new NodeJSCodePathMapper();
       GapicProvider<? extends Object> mainProvider =
           CommonGapicProvider.<Interface>newBuilder()
               .setModel(model)

src/main/java/com/google/api/codegen/nodejs/NodeJSCodePathMapper.java

@@ -0,0 +1,45 @@
+/* Copyright 2016 Google Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.api.codegen.nodejs;
+
+import com.google.api.codegen.ApiConfig;
+import com.google.api.codegen.gapic.GapicCodePathMapper;
+import com.google.api.tools.framework.model.ProtoElement;
+
+import com.google.common.base.Splitter;
+
+import java.util.List;
+
+public class NodeJSCodePathMapper implements GapicCodePathMapper {
+  @Override
+  public String getOutputPath(ProtoElement element, ApiConfig config) {
+    String apiVersion = "";
+    // For the gcloud package, the generated file would be a sub part of
+    // the package, under the versioned directory. For example, Speech V1 API
+    // would be a part of "@google-cloud/speech" package, and loaded as
+    //    var speechV1 = require("@google-cloud/speech").v1();
+    // To do this, we fetch the version number from the service full name.
+    if (NodeJSUtils.isGcloud(config)) {
+      List<String> packages = Splitter.on(".").splitToList(element.getFullName());
+      if (packages.size() > 2) {
+        String parentName = packages.get(packages.size() - 2);
+        if (parentName.matches("v[0-9]+((alpha|beta)[0-9]+)?")) {
+          apiVersion = parentName;
+        }
+      }
+    }
+    return apiVersion.isEmpty() ? "src" : ("src/" + apiVersion);
+  }
+}

src/main/java/com/google/api/codegen/nodejs/NodeJSGapicContext.java

@@ -74,8 +74,37 @@ public String grpcClientName(Interface service) {
   }
 
   public boolean isGcloud() {
-    String packageName = getApiConfig().getPackageName();
-    return !Strings.isNullOrEmpty(packageName) && packageName.startsWith("@google-cloud/");
+    return NodeJSUtils.isGcloud(getApiConfig());
+  }
+
+  /**
+   * The namespace (full package name) for the service.
+   */
+  public String getNamespace(Interface service) {
+    String fullName = service.getFullName();
+    int slash = fullName.lastIndexOf('.');
+    return fullName.substring(0, slash);
+  }
+
+  /**
+   * The name for the module for this vkit module. This assumes that the service's
+   * full name will be in the format of 'google.some.apiname.version.ServiceName',
+   * and extracts the 'apiname' and 'version' part and combine them to lower-camelcased
+   * style (like pubsubV1).
+   */
+  public String getModuleName(Interface service) {
+    List<String> names = Splitter.on(".").splitToList(service.getFullName());
+    return names.get(names.size() - 3) + lowerUnderscoreToUpperCamel(names.get(names.size() - 2));
+  }
+
+  /**
+   * Returns the major version part in the API namespace. This assumes that the service's
+   * full name will be in the format of 'google.some.apiname.version.ServiceName', and
+   * extracts the 'version' part.
+   */
+  public String getApiVersion(Interface service) {
+    List<String> names = Splitter.on(".").splitToList(service.getFullName());
+    return names.get(names.size() - 2);
   }
 
   /**
@@ -104,6 +133,7 @@ private String fieldParamComment(Field field, String paramComment, boolean isOpt
     String fieldName = wrapIfKeywordOrBuiltIn(lowerUnderscoreToLowerCamel(field.getSimpleName()));
     if (isOptional) {
       fieldName = "otherArgs." + fieldName;
+      commentType = commentType + "=";
     }
     return fieldComment(
         String.format("@param {%s} %s", commentType, fieldName), paramComment, field);
@@ -162,9 +192,9 @@ private String returnTypeComment(Method method, MethodConfig config) {
               + "  a gax.BundleEventEmitter but the API is immediately invoked, so it behaves same\n"
               + "  as a gax.EventEmitter does.";
     }
-    return "@param {?"
+    return "@param {"
         + callbackType
-        + "} callback\n"
+        + "=} callback\n"
         + "  The function which will be called with the result of the API call.\n"
         + returnMessage;
   }
@@ -184,7 +214,7 @@ public List<String> methodComments(Method msg) {
     }
     Iterable<Field> optionalParams = removePageTokenFromFields(config.getOptionalFields(), config);
     if (optionalParams.iterator().hasNext()) {
-      paramTypesBuilder.append("@param {?Object} otherArgs\n");
+      paramTypesBuilder.append("@param {Object=} otherArgs\n");
       for (Field field : optionalParams) {
         if (config.isPageStreaming()
             && field.equals((config.getPageStreaming().getPageSizeField()))) {
@@ -203,7 +233,7 @@ public List<String> methodComments(Method msg) {
       }
     }
     paramTypesBuilder.append(
-        "@param {?gax.CallOptions} options\n"
+        "@param {gax.CallOptions=} options\n"
             + "  Overrides the default settings for this call, e.g, timeout,\n"
             + "  retries, etc.");
     String paramTypes = paramTypesBuilder.toString();

src/main/java/com/google/api/codegen/nodejs/NodeJSUtils.java

@@ -0,0 +1,30 @@
+/* Copyright 2016 Google Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.api.codegen.nodejs;
+
+import com.google.api.codegen.ApiConfig;
+import com.google.common.base.Strings;
+
+public class NodeJSUtils {
+  /**
+   * Returns true if the current API is a part of gcloud (i.e. cloud API).
+   * This can be known if the package name configuration is in the pattern
+   * of "@google-cloud/(API_NAME)".
+   */
+  public static boolean isGcloud(ApiConfig config) {
+    String packageName = config.getPackageName();
+    return !Strings.isNullOrEmpty(packageName) && packageName.startsWith("@google-cloud/");
+  }
+}