[Cronet] Fix up javadocs for EffectiveConnectionType

build/android/gyp/java_cpp_enum.py

 #!/usr/bin/env python
 #
 # Copyright 2014 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 import collections
 from datetime import date
 import re
 import optparse
 import os
 from string import Template
 import sys
 import textwrap
 import zipfile
 
 from util import build_utils
 
 # List of C++ types that are compatible with the Java code generated by this
 # script.
 #
 # This script can parse .idl files however, at present it ignores special
 # rules such as [cpp_enum_prefix_override="ax_attr"].
 ENUM_FIXED_TYPE_WHITELIST = ['char', 'unsigned char',
   'short', 'unsigned short',
   'int', 'int8_t', 'int16_t', 'int32_t', 'uint8_t', 'uint16_t']
 
 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
     self.entries = collections.OrderedDict(entries or [])
     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:
       raise Exception('Multiple definitions of key %s found.' % key)
     self.entries[key] = value
 
   def AppendEntryComment(self, key, value):
     if key in self.comments:
       raise Exception('Multiple definitions of key %s found.' % key)
     self.comments[key] = value
@@ skipping 50 matching lines @@
       else:
         stripped_value = v
       entries[stripped_key] = stripped_value
 
     self.entries = entries
 
 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 = {}
 
   def Update(self, key, value):
     if key not in DirectiveSet.known_keys:
       raise Exception("Unknown directive: " + key)
     self._directives[key] = value
 
   @property
   def empty(self):
     return len(self._directives) == 0
 
   def UpdateDefinition(self, definition):
     definition.class_name_override = self._directives.get(
         DirectiveSet.class_name_override_key, '')
     definition.enum_package = self._directives.get(
         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):
   single_line_comment_re = re.compile(r'\s*//\s*([^\n]+)')
   multi_line_comment_start_re = re.compile(r'\s*/\*')
   enum_line_re = re.compile(r'^\s*(\w+)(\s*\=\s*([^,\n]+))?,?')
   enum_end_re = re.compile(r'^\s*}\s*;\.*$')
   generator_directive_re = re.compile(
       r'^\s*//\s+GENERATED_JAVA_(\w+)\s*:\s*([\.\w]+)$')
   multi_line_generator_directive_start_re = re.compile(
       r'^\s*//\s+GENERATED_JAVA_(\w+)\s*:\s*\(([\.\w]*)$')
   multi_line_directive_continuation_re = re.compile(
       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+)'
   optional_fixed_type_re = r'(\:\s*(\w+\s*\w+?))?'
   enum_start_re = re.compile(r'^\s*(?:\[cpp.*\])?\s*enum\s+' +
       optional_class_or_struct_re + '\s*' + enum_name_re + '\s*' +
       optional_fixed_type_re + '\s*{\s*$')
 
   def __init__(self, lines, path=None):
     self._lines = lines
     self._path = path
     self._enum_definitions = []
     self._in_enum = False
     self._current_definition = None
     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)
     self._generator_directives = DirectiveSet()
 
   def ParseDefinitions(self):
     for line in self._lines:
       self._ParseLine(line)
     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)
     else:
       self._ParseEnumLine(line)
 
   def _ParseEnumLine(self, line):
     enum_comment = HeaderParser.single_line_comment_re.match(line)
     if enum_comment:
       self._current_comments.append(enum_comment.groups()[0])
@@ skipping 10 matching lines @@
       self._in_enum = False
     elif enum_entry:
       enum_key = enum_entry.groups()[0]
       enum_value = enum_entry.groups()[2]
       self._current_definition.AppendEntry(enum_key, enum_value)
       if self._current_comments:
          self._current_definition.AppendEntryComment(
                  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))
     multi_line_directive_end = (
         HeaderParser.multi_line_directive_end_re.match(line))
 
     if multi_line_directive_continuation:
       value_cont = multi_line_directive_continuation.groups()[0]
       self._multi_line_generator_directive[1].append(value_cont)
     elif multi_line_directive_end:
       directive_name = self._multi_line_generator_directive[0]
       directive_value = "".join(self._multi_line_generator_directive[1])
       directive_value += multi_line_directive_end.groups()[0]
       self._multi_line_generator_directive = None
       self._generator_directives.Update(directive_name, directive_value)
     else:
       raise Exception('Malformed multi-line directive declaration in ' +
                       self._path)
 
   def _ParseRegularLine(self, line):
     enum_start = HeaderParser.enum_start_re.match(line)
     generator_directive = HeaderParser.generator_directive_re.match(line)
     multi_line_generator_directive_start = (
         HeaderParser.multi_line_generator_directive_start_re.match(line))
+    class_comment_directive_start = (
+        HeaderParser.class_comment_directive_start_re.match(line))
 
-    if generator_directive:
+    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)
     elif multi_line_generator_directive_start:
       directive_name = multi_line_generator_directive_start.groups()[0]
       directive_value = multi_line_generator_directive_start.groups()[1]
       self._multi_line_generator_directive = (directive_name, [directive_value])
     elif enum_start:
       if self._generator_directives.empty:
         return
@@ skipping 37 matching lines @@
 // From
 //     ${SOURCE_PATH}
 
 package ${PACKAGE};
 
 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}
   })
   @Retention(RetentionPolicy.SOURCE)
   public @interface ${ANNOTATION} {}
 ${ENUM_ENTRIES}
 }
 """)
 
   enum_template = Template('  public static final int ${NAME} = ${VALUE};')
@@ skipping 24 matching lines @@
                                  subsequent_indent = enum_names_indent,
                                  width = 100)
   enum_names_string = '\n'.join(wrapper.wrap(', '.join(enum_names)))
 
   annotation_template = Template('${NAME}Enum')
   annotation_values = { 'NAME': enum_definition.class_name, }
   annotation_name = annotation_template.substitute(annotation_values)
 
   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,
       'ANNOTATION': annotation_name,
       'SCRIPT_NAME': GetScriptName(),
       'SOURCE_PATH': source_path,
       'YEAR': str(date.today().year)
   }
   return template.substitute(values)
 
@@ skipping 67 matching lines @@
     if options.verbose:
       print 'Output paths:'
       print '\n'.join(output_paths)
 
     # Used by GYP.
     return ' '.join(output_paths)
 
 
 if __name__ == '__main__':
   DoMain(sys.argv[1:])