Second half of HTML json docs. This reads the json file and inserts the docs.

tools/dom/scripts/generator.py

 #!/usr/bin/python
 # Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 # for details. All rights reserved. Use of this source code is governed by a
 # BSD-style license that can be found in the LICENSE file.
 
 """This module provides shared functionality for systems to generate
 Dart APIs from the IDL database."""
 
 import copy
+import json
+import os
 import re
 from htmlrenamer import html_interface_renames
 
+# Set up json file for retrieving comments.
+current_dir = os.path.dirname(__file__)

[blois, 2013/01/25 19:16:32]

should be private types (_current_dir, etc).

[Andrei Mouravski, 2013/01/25 19:23:31]

Done.

+json_path = os.path.join(current_dir, '..', 'docs', 'docs.json')
+dom_json = json.load(open(json_path))
+
 _pure_interfaces = set([
     # TODO(sra): DOMStringMap should be a class implementing Map<String,String>.
     'DOMStringMap',
     'ElementTimeControl',
     'ElementTraversal',
     'EventListener',
     'MediaQueryListListener',
     'MutationCallback',
     'NodeSelector',
     'SVGExternalResourcesRequired',
@@ skipping 765 matching lines @@
   'SpeechRecognitionResult': _speech_recognition_annotations,
   'WebSocket': _all_but_ie9_annotations,
   'WorkerContext.indexedDB': _indexed_db_annotations,
   'WorkerContext.webkitRequestFileSystem': _file_system_annotations,
   'WorkerContext.webkitRequestFileSystemSync': _file_system_annotations,
   'WorkerContext.webkitResolveLocalFileSystemSyncURL': _file_system_annotations,
   'WorkerContext.webkitResolveLocalFileSystemURL': _file_system_annotations,
   'XMLHttpRequestProgressEvent': _webkit_experimental_annotations,
 }
 
-def FindCommonAnnotations(interface_name, member_name=None):
+def GetComments(interface_name, member_name=None, library_name=None):
+  """ Finds all comments for the interface or member and returns a list. """
+
+  # Add documentation from JSON.
+  comments = []
+
+  if library_name in dom_json and interface_name in dom_json[library_name]:
+    if member_name and (member_name in
+                        dom_json[library_name][interface_name]['members']):
+      comments = dom_json[library_name][interface_name]['members'][member_name]
+    elif 'comment' in dom_json[library_name][interface_name]:
+      comments = dom_json[library_name][interface_name]['comment']
+
+  return comments
+
+def GetAnnotationsAndComments(interface_name, member_name=None,
+                              library_name=None):
+  annotations = GetComments(interface_name, member_name, library_name)
+  annotations.extend(FindCommonAnnotations(interface_name, member_name,
+                                           library_name))
+  return annotations
+
+def FindCommonAnnotations(interface_name, member_name=None, library_name=None):
   """ Finds annotations common between dart2js and dartium.
   """
   if member_name:
     key = '%s.%s' % (interface_name, member_name)
   else:
     key = interface_name
 
-  annotations = ["@DomName('" + key + "')",]
+  annotations = ["@DomName('" + key + "')"]
+
   # Only add this for members, so we don't add DocsEditable to templated classes
   # (they get it from the default class template)
   if member_name:
     annotations.append('@DocsEditable');
 
   if (dart_annotations.get(key) != None):
     annotations.extend(dart_annotations.get(key))
 
   return annotations
 
-def FindDart2JSAnnotations(idl_type, interface_name, member_name):
+def FindDart2JSAnnotationsAndComments(idl_type, interface_name, member_name,
+                           library_name=None):
   """ Finds all annotations for Dart2JS members- including annotations for
   both dart2js and dartium.
   """
-  annotations = FindCommonAnnotations(interface_name, member_name)
+  annotations = GetAnnotationsAndComments(interface_name, member_name,
+                                          library_name)
 
   ann2 = _FindDart2JSSpecificAnnotations(idl_type, interface_name, member_name)
   if ann2:
     if annotations:
       annotations.extend(ann2)
     else:
       annotations = ann2
   return annotations
 
 def AnyConversionAnnotations(idl_type, interface_name, member_name):
   if (dart_annotations.get('%s.%s' % (interface_name, member_name)) or
       _FindDart2JSSpecificAnnotations(idl_type, interface_name, member_name)):
     return True
   else:
     return False
 
-def FormatAnnotations(annotations, indentation):
+def FormatAnnotationsAndComments(annotations, indentation):
   if annotations:
     newline = '\n%s' % indentation
     result = newline.join(annotations) + newline
     return result
   return ''
 
 def _FindDart2JSSpecificAnnotations(idl_type, interface_name, member_name):
   """ Finds dart2js-specific annotations. This does not include ones shared with
   dartium.
   """
@@ skipping 540 matching lines @@
                                   self)
 
     if type_data.clazz == 'SVGTearOff':
       dart_interface_name = self._renamer.RenameInterface(
           self._database.GetInterface(type_name))
       return SVGTearOffIDLTypeInfo(
           type_name, type_data, dart_interface_name, self)
 
     class_name = '%sIDLTypeInfo' % type_data.clazz
     return globals()[class_name](type_name, type_data)