[Cronet] Fix up javadocs for EffectiveConnectionType

build/android/gyp/java_cpp_enum.py

Index: build/android/gyp/java_cpp_enum.py
diff --git a/build/android/gyp/java_cpp_enum.py b/build/android/gyp/java_cpp_enum.py
index ffab05c9155848f6bce8f9339a729e911741560c..95a8214a9a359c4c40f8c2db91401b2f7fe7aeed 100755
--- a/build/android/gyp/java_cpp_enum.py
+++ b/build/android/gyp/java_cpp_enum.py
@@ -27,7 +27,8 @@ ENUM_FIXED_TYPE_WHITELIST = ['char', 'unsigned char',
 
 class EnumDefinition(object):
   def __init__(self, original_enum_name=None, class_name_override=None,
-               enum_package=None, entries=None, comments=None, fixed_type=None):
+               enum_package=None, entries=None, comments=None, fixed_type=None,
+               class_comment=None):
     self.original_enum_name = original_enum_name
     self.class_name_override = class_name_override
     self.enum_package = enum_package
@@ -35,6 +36,7 @@ class EnumDefinition(object):
     self.comments = collections.OrderedDict(comments or [])
     self.prefix_to_strip = None
     self.fixed_type = fixed_type
+    self.class_comment = class_comment
 
   def AppendEntry(self, key, value):
     if key in self.entries:
@@ -105,8 +107,10 @@ class DirectiveSet(object):
   class_name_override_key = 'CLASS_NAME_OVERRIDE'
   enum_package_key = 'ENUM_PACKAGE'
   prefix_to_strip_key = 'PREFIX_TO_STRIP'
+  class_comment_key = 'CLASS_COMMENT'
 
-  known_keys = [class_name_override_key, enum_package_key, prefix_to_strip_key]
+  known_keys = [class_name_override_key, enum_package_key, prefix_to_strip_key,
+      class_comment_key]
 
   def __init__(self):
     self._directives = {}
@@ -127,6 +131,8 @@ class DirectiveSet(object):
         DirectiveSet.enum_package_key)
     definition.prefix_to_strip = self._directives.get(
         DirectiveSet.prefix_to_strip_key)
+    definition.class_comment = self._directives.get(
+        DirectiveSet.class_comment_key, '')
 
 
 class HeaderParser(object):
@@ -142,6 +148,12 @@ class HeaderParser(object):
       r'^\s*//\s+([\.\w]+)$')
   multi_line_directive_end_re = re.compile(
       r'^\s*//\s+([\.\w]*)\)$')
+  class_comment_directive_start_re = re.compile(
+      r'^\s*//\s+GENERATED_JAVA_(\w+)_BEGIN\s*:$')
+  class_comment_directive_continuation_re = re.compile(
+      r'^\s*//(.*)$')
+  class_comment_directive_end_re = re.compile(
+      r'^\s*//\s+GENERATED_JAVA_(\w+)_END$')
 
   optional_class_or_struct_re = r'(class|struct)?'
   enum_name_re = r'(\w+)'
@@ -159,6 +171,7 @@ class HeaderParser(object):
     self._current_comments = []
     self._generator_directives = DirectiveSet()
     self._multi_line_generator_directive = None
+    self._class_comment_directive = None
 
   def _ApplyGeneratorDirectives(self):
     self._generator_directives.UpdateDefinition(self._current_definition)
@@ -170,7 +183,9 @@ class HeaderParser(object):
     return self._enum_definitions
 
   def _ParseLine(self, line):
-    if self._multi_line_generator_directive:
+    if self._class_comment_directive:
+      self._ParseClassCommentDirectiveLine(line)
+    elif self._multi_line_generator_directive:
       self._ParseMultiLineDirectiveLine(line)
     elif not self._in_enum:
       self._ParseRegularLine(line)
@@ -201,6 +216,25 @@ class HeaderParser(object):
                  enum_key, ' '.join(self._current_comments))
          self._current_comments = []
 
+  def _ParseClassCommentDirectiveLine(self, line):
+    class_comment_directive_continuation = (
+        HeaderParser.class_comment_directive_continuation_re.match(line))
+    class_comment_directive_end = (
+        HeaderParser.class_comment_directive_end_re.match(line))
+
+    if class_comment_directive_end:
+      directive_name = self._class_comment_directive[0]
+      directive_value = "".join(self._class_comment_directive[1])
+      self._class_comment_directive = None
+      self._generator_directives.Update(directive_name, directive_value)
+    elif class_comment_directive_continuation:
+      value_cont = class_comment_directive_continuation.groups()[0]
+      self._class_comment_directive[1].append(value_cont)
+    else:
+      raise Exception('Malformed class comment directive declaration in ' +
+                      self._path)
+
+
   def _ParseMultiLineDirectiveLine(self, line):
     multi_line_directive_continuation = (
         HeaderParser.multi_line_directive_continuation_re.match(line))
@@ -225,8 +259,14 @@ class HeaderParser(object):
     generator_directive = HeaderParser.generator_directive_re.match(line)
     multi_line_generator_directive_start = (
         HeaderParser.multi_line_generator_directive_start_re.match(line))
-
-    if generator_directive:
+    class_comment_directive_start = (
+        HeaderParser.class_comment_directive_start_re.match(line))
+
+    if class_comment_directive_start:
+      directive_name = class_comment_directive_start.groups()[0]
+      directive_value = ''
+      self._class_comment_directive = (directive_name, [directive_value])
+    elif generator_directive:
       directive_name = generator_directive.groups()[0]
       directive_value = generator_directive.groups()[1]
       self._generator_directives.Update(directive_name, directive_value)
@@ -284,7 +324,9 @@ import android.support.annotation.IntDef;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/** ${CLASS_COMMENT} */
 public class ${CLASS_NAME} {
+  /** @hide */

[agrieve, 2016/09/14 00:43:45]

Should @hide really be added unconditionally here?

[pauljensen, 2016/09/14 18:01:13]

The alternative would be to add a comment describing the @IntDef annotation.  I
figured for now hiding it was fine; this is what we do for all other @IntDef
annotations in Cronet.  It can still be used in chromium, it just won't appear
in javadocs.

[agrieve, 2016/09/14 19:04:44]

Sounds good then. I think likely cronet is the only user of this atm, so we can
always revisit if we want later. I also recently learned that with .aar files,
some support libraries bundle in an "annotations.xml" that contain @IntDef
information, so that's probably the correct longer-term approach.

   @IntDef({
 ${INT_DEF}
   })
@@ -329,6 +371,7 @@ ${ENUM_ENTRIES}
 
   values = {
       'CLASS_NAME': enum_definition.class_name,
+      'CLASS_COMMENT': enum_definition.class_comment,
       'ENUM_ENTRIES': enum_entries_string,
       'PACKAGE': enum_definition.enum_package,
       'INT_DEF': enum_names_string,