diff options
Diffstat (limited to 'tools/json_schema_compiler')
32 files changed, 59 insertions, 10 deletions
diff --git a/tools/json_schema_compiler/dart_test/dictionaries.idl b/tools/json_schema_compiler/dart_test/dictionaries.idl index 4b26684..1eb9e25 100644 --- a/tools/json_schema_compiler/dart_test/dictionaries.idl +++ b/tools/json_schema_compiler/dart_test/dictionaries.idl @@ -2,6 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// This comment is for the dictionaries namespace. namespace dictionaries { // Documentation for ComplexType. dictionary InnerType { diff --git a/tools/json_schema_compiler/dart_test/empty_namespace.idl b/tools/json_schema_compiler/dart_test/empty_namespace.idl index 5a5ea03..824de2d 100644 --- a/tools/json_schema_compiler/dart_test/empty_namespace.idl +++ b/tools/json_schema_compiler/dart_test/empty_namespace.idl @@ -2,5 +2,6 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// An empty comment is required for an empty namespace. namespace empty_namespace { }; diff --git a/tools/json_schema_compiler/dart_test/empty_type.idl b/tools/json_schema_compiler/dart_test/empty_type.idl index af5de84..9d7de6f 100644 --- a/tools/json_schema_compiler/dart_test/empty_type.idl +++ b/tools/json_schema_compiler/dart_test/empty_type.idl @@ -2,6 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// Namespace-level comment for EmptyType. namespace empty_type { // Documentation for EmptyType. dictionary EmptyType { diff --git a/tools/json_schema_compiler/dart_test/enums.idl b/tools/json_schema_compiler/dart_test/enums.idl index 18ea85a..1c82d00 100644 --- a/tools/json_schema_compiler/dart_test/enums.idl +++ b/tools/json_schema_compiler/dart_test/enums.idl @@ -2,6 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// A comment for the enums namespace. namespace enums { // A basic enumeration. enum Enum1 { a, b }; diff --git a/tools/json_schema_compiler/dart_test/events.idl b/tools/json_schema_compiler/dart_test/events.idl index 54c711a..f1fb4b6 100644 --- a/tools/json_schema_compiler/dart_test/events.idl +++ b/tools/json_schema_compiler/dart_test/events.idl @@ -2,6 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// This comment is for the events namespace. namespace events { dictionary EventArgumentElement { DOMString elementStringArg; diff --git a/tools/json_schema_compiler/dart_test/functions.idl b/tools/json_schema_compiler/dart_test/functions.idl index e2283c6..e303d0d 100644 --- a/tools/json_schema_compiler/dart_test/functions.idl +++ b/tools/json_schema_compiler/dart_test/functions.idl @@ -2,6 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// A comment for the functions namespace. namespace functions { callback SimpleCallback = void (); diff --git a/tools/json_schema_compiler/dart_test/operatable_type.idl b/tools/json_schema_compiler/dart_test/operatable_type.idl index 74ce534..9c5f53c 100644 --- a/tools/json_schema_compiler/dart_test/operatable_type.idl +++ b/tools/json_schema_compiler/dart_test/operatable_type.idl @@ -2,6 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// Top-level namespace-comment for operatableType namespace operatable_type { dictionary DictType { int x; @@ -28,4 +29,4 @@ namespace operatable_type { // Function taking dict type. static void dictArgFunc(DictType d); }; -};
\ No newline at end of file +}; diff --git a/tools/json_schema_compiler/dart_test/tags.idl b/tools/json_schema_compiler/dart_test/tags.idl index f4ddff4..7a029cd 100644 --- a/tools/json_schema_compiler/dart_test/tags.idl +++ b/tools/json_schema_compiler/dart_test/tags.idl @@ -2,30 +2,31 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// A comment describing tags. namespace tags { // This dictionary has the property [inline_doc]. [inline_doc] dictionary InlineDoc { }; - + // This dictionary has the property [nodoc]. [nodoc] dictionary Nodoc { }; - + // This dictionary has the property [nocompile]. [nocompile] dictionary Nocompile { }; - + // This dictionary has no tags on the dictionary itself. dictionary PlainDict { // This int has the property [inline_doc]. [inline_doc] int inline_doc; - + // This String has the property [nodoc]. [nodoc] String nodoc; - + // This double has the property [nocompile]. [nocompile] double nocompile; - + // This object has the property [instanceOf=fileEntry]. [instanceOf=fileEntry] object instance_of_tag; }; diff --git a/tools/json_schema_compiler/idl_schema.py b/tools/json_schema_compiler/idl_schema.py index 519ae56..8197f31 100644 --- a/tools/json_schema_compiler/idl_schema.py +++ b/tools/json_schema_compiler/idl_schema.py @@ -309,7 +309,7 @@ class Namespace(object): dictionary that the JSON schema compiler expects to see. ''' - def __init__(self, namespace_node, nodoc=False, internal=False): + def __init__(self, namespace_node, description, nodoc=False, internal=False): self.namespace = namespace_node self.nodoc = nodoc self.internal = internal @@ -317,6 +317,7 @@ class Namespace(object): self.functions = [] self.types = [] self.callbacks = OrderedDict() + self.description = description def process(self): for node in self.namespace.children: @@ -334,6 +335,7 @@ class Namespace(object): else: sys.exit('Did not process %s %s' % (node.cls, node)) return {'namespace': self.namespace.GetName(), + 'description': self.description, 'nodoc': self.nodoc, 'types': self.types, 'functions': self.functions, @@ -361,16 +363,20 @@ class IDLSchema(object): namespaces = [] nodoc = False internal = False + description = None for node in self.idl: if node.cls == 'Namespace': - namespace = Namespace(node, nodoc, internal) + if not description: + raise ValueError('%s must have a namespace-level comment. This will ' + 'appear on the API summary page.' % node.GetName()) + namespace = Namespace(node, description, nodoc, internal) namespaces.append(namespace.process()) nodoc = False internal = False elif node.cls == 'Copyright': continue elif node.cls == 'Comment': - continue + description = node.GetName() elif node.cls == 'ExtAttribute': if node.name == 'nodoc': nodoc = bool(node.value) diff --git a/tools/json_schema_compiler/json_schema_test.py b/tools/json_schema_compiler/json_schema_test.py index ffba653..11ba61e 100755 --- a/tools/json_schema_compiler/json_schema_test.py +++ b/tools/json_schema_compiler/json_schema_test.py @@ -12,12 +12,14 @@ class JsonSchemaUnittest(unittest.TestCase): compiled = [ { "namespace": "compile", + "description": "The compile API.", "functions": [], "types": {} }, { "namespace": "functions", + "description": "The functions API.", "functions": [ { "id": "two" @@ -34,6 +36,7 @@ class JsonSchemaUnittest(unittest.TestCase): { "namespace": "types", + "description": "The types API.", "functions": [ { "id": "one" } ], @@ -49,6 +52,7 @@ class JsonSchemaUnittest(unittest.TestCase): { "namespace": "nested", + "description": "The nested API.", "properties": { "sync": { "functions": [ diff --git a/tools/json_schema_compiler/model.py b/tools/json_schema_compiler/model.py index d6b6efc..d49c18f 100644 --- a/tools/json_schema_compiler/model.py +++ b/tools/json_schema_compiler/model.py @@ -39,6 +39,7 @@ class Namespace(object): Properties: - |name| the name of the namespace + - |description| the description of the namespace - |unix_name| the unix_name of the namespace - |source_file| the file that contained the namespace definition - |source_file_dir| the directory component of |source_file| @@ -54,6 +55,10 @@ class Namespace(object): """ def __init__(self, json, source_file, include_compiler_options=False): self.name = json['namespace'] + if 'description' not in json: + raise ValueError('%s must have a "description" field. This will appear ' + 'on the API summary page.' % self.name) + self.description = json.get('description', None) self.unix_name = UnixName(self.name) self.source_file = source_file self.source_file_dir, self.source_file_filename = os.path.split(source_file) diff --git a/tools/json_schema_compiler/test/additional_properties.json b/tools/json_schema_compiler/test/additional_properties.json index 0b800d9..a40c479 100644 --- a/tools/json_schema_compiler/test/additional_properties.json +++ b/tools/json_schema_compiler/test/additional_properties.json @@ -1,6 +1,7 @@ [ { "namespace": "additionalProperties", + "description": "The additionalProperties API.", "types": [ { "id": "AdditionalPropertiesType", diff --git a/tools/json_schema_compiler/test/any.json b/tools/json_schema_compiler/test/any.json index 55da4a6..d836a04 100644 --- a/tools/json_schema_compiler/test/any.json +++ b/tools/json_schema_compiler/test/any.json @@ -1,6 +1,7 @@ [ { "namespace": "any", + "description": "The any API.", "types": [ { "id": "AnyType", diff --git a/tools/json_schema_compiler/test/arrays.json b/tools/json_schema_compiler/test/arrays.json index a0edd54..690d5cb 100644 --- a/tools/json_schema_compiler/test/arrays.json +++ b/tools/json_schema_compiler/test/arrays.json @@ -1,6 +1,7 @@ [ { "namespace": "arrays", + "description": "The arrays API.", "types": [ { "id": "EnumArrayType", diff --git a/tools/json_schema_compiler/test/browser_action.json b/tools/json_schema_compiler/test/browser_action.json index 6288fab..934d56d 100644 --- a/tools/json_schema_compiler/test/browser_action.json +++ b/tools/json_schema_compiler/test/browser_action.json @@ -5,6 +5,7 @@ [ { "namespace": "browserAction", + "description": "The browserAction API.", "dependencies": [ "tabs" ], "types": [ { diff --git a/tools/json_schema_compiler/test/callbacks.json b/tools/json_schema_compiler/test/callbacks.json index 06455b9..2f86c26 100644 --- a/tools/json_schema_compiler/test/callbacks.json +++ b/tools/json_schema_compiler/test/callbacks.json @@ -1,6 +1,7 @@ [ { "namespace": "callbacks", + "description": "The callbacks API.", "types": [], "functions": [ { diff --git a/tools/json_schema_compiler/test/choices.json b/tools/json_schema_compiler/test/choices.json index 24683c4..29afb47 100644 --- a/tools/json_schema_compiler/test/choices.json +++ b/tools/json_schema_compiler/test/choices.json @@ -1,6 +1,7 @@ [ { "namespace": "choices", + "description": "The choices API.", "types": [ { "id": "ChoiceType", diff --git a/tools/json_schema_compiler/test/content_settings.json b/tools/json_schema_compiler/test/content_settings.json index 2d6e803..6fac436 100644 --- a/tools/json_schema_compiler/test/content_settings.json +++ b/tools/json_schema_compiler/test/content_settings.json @@ -5,6 +5,7 @@ [ { "namespace": "contentSettings", + "description": "The contentSettings API.", "types": [ { "id": "ResourceIdentifier", diff --git a/tools/json_schema_compiler/test/crossref.json b/tools/json_schema_compiler/test/crossref.json index 9d3f905..a1e994b 100644 --- a/tools/json_schema_compiler/test/crossref.json +++ b/tools/json_schema_compiler/test/crossref.json @@ -1,6 +1,7 @@ [ { "namespace": "crossref", + "description": "The crossref API.", "dependencies": ["simple_api"], "types": [ { diff --git a/tools/json_schema_compiler/test/dependency_tester.json b/tools/json_schema_compiler/test/dependency_tester.json index 15ff4ac..4845136 100644 --- a/tools/json_schema_compiler/test/dependency_tester.json +++ b/tools/json_schema_compiler/test/dependency_tester.json @@ -5,6 +5,7 @@ [ { "namespace": "dependencyTester", + "description": "An API for testing dependencies.", "dependencies": [ "browserAction", "fontSettings" ], "types": [], "functions": [ diff --git a/tools/json_schema_compiler/test/enums.json b/tools/json_schema_compiler/test/enums.json index 6769b19..19229b0 100644 --- a/tools/json_schema_compiler/test/enums.json +++ b/tools/json_schema_compiler/test/enums.json @@ -1,6 +1,7 @@ [ { "namespace": "enums", + "description": "The enums API.", "types": [ { "id": "Enumeration", diff --git a/tools/json_schema_compiler/test/font_settings.json b/tools/json_schema_compiler/test/font_settings.json index 0326aca..01c49f7 100644 --- a/tools/json_schema_compiler/test/font_settings.json +++ b/tools/json_schema_compiler/test/font_settings.json @@ -5,6 +5,7 @@ [ { "namespace": "fontSettings", + "description": "The fontSettings API.", "types": [ { "id": "FontName", diff --git a/tools/json_schema_compiler/test/forbidden.json b/tools/json_schema_compiler/test/forbidden.json index c7978aa..841b0e1 100644 --- a/tools/json_schema_compiler/test/forbidden.json +++ b/tools/json_schema_compiler/test/forbidden.json @@ -1,6 +1,7 @@ [ { "namespace": "forbidden", + "description": "The forbidden API... Careful.", "types": [], "functions": [ { diff --git a/tools/json_schema_compiler/test/functions_as_parameters.json b/tools/json_schema_compiler/test/functions_as_parameters.json index cdc47ff..b948616 100644 --- a/tools/json_schema_compiler/test/functions_as_parameters.json +++ b/tools/json_schema_compiler/test/functions_as_parameters.json @@ -1,6 +1,7 @@ [ { "namespace": "functions_as_parameters", + "description": "The functionsAsParameters API", "types": [ { "id": "FunctionType", diff --git a/tools/json_schema_compiler/test/functions_on_types.json b/tools/json_schema_compiler/test/functions_on_types.json index e8c8220..a20a75f 100644 --- a/tools/json_schema_compiler/test/functions_on_types.json +++ b/tools/json_schema_compiler/test/functions_on_types.json @@ -1,6 +1,7 @@ [ { "namespace": "functionsOnTypes", + "description": "The functionsOnTypes API.", "types": [ { "id": "StorageArea", diff --git a/tools/json_schema_compiler/test/idl_reserved_words.idl b/tools/json_schema_compiler/test/idl_reserved_words.idl index 61ddabd..411973e 100644 --- a/tools/json_schema_compiler/test/idl_reserved_words.idl +++ b/tools/json_schema_compiler/test/idl_reserved_words.idl @@ -2,6 +2,8 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +// Tests 'reserved words' in various places in IDL. + namespace reserved_words { enum Foo { _float, _DOMString }; diff --git a/tools/json_schema_compiler/test/json_schema_test.json b/tools/json_schema_compiler/test/json_schema_test.json index 0ac9131..b3b24e9 100644 --- a/tools/json_schema_compiler/test/json_schema_test.json +++ b/tools/json_schema_compiler/test/json_schema_test.json @@ -1,12 +1,14 @@ [ { "namespace": "compile", + "description": "The compile API.", "functions": [], "types": {} }, { "namespace": "nocompile", + "description": "The nocompile API.", "nocompile": true, "functions": [], "types": {} @@ -14,6 +16,7 @@ { "namespace": "functions", + "description": "The functions API.", "functions": [ { "id": "one", @@ -38,6 +41,7 @@ { "namespace": "types", + "description": "The types API.", "functions": [ { "id": "one" } ], @@ -61,6 +65,7 @@ { "namespace": "nested", + "description": "The nested API.", "properties": { "sync": { "functions": [ diff --git a/tools/json_schema_compiler/test/objects.json b/tools/json_schema_compiler/test/objects.json index 00a7f53..e76e229 100644 --- a/tools/json_schema_compiler/test/objects.json +++ b/tools/json_schema_compiler/test/objects.json @@ -1,6 +1,7 @@ [ { "namespace": "objects", + "description": "The objects API.", "types": [], "functions": [ { diff --git a/tools/json_schema_compiler/test/permissions.json b/tools/json_schema_compiler/test/permissions.json index 1f4cb9f..df97441 100644 --- a/tools/json_schema_compiler/test/permissions.json +++ b/tools/json_schema_compiler/test/permissions.json @@ -1,6 +1,7 @@ [ { "namespace": "permissions", + "description": "A test API for the json_schema_compiler.", "types": [ { "id": "Permissions", diff --git a/tools/json_schema_compiler/test/simple_api.json b/tools/json_schema_compiler/test/simple_api.json index 82d77b8..9ab5403 100644 --- a/tools/json_schema_compiler/test/simple_api.json +++ b/tools/json_schema_compiler/test/simple_api.json @@ -1,6 +1,7 @@ [ { "namespace": "simple_api", + "description": "This is a simple API.", "types": [ { "id": "TestType", diff --git a/tools/json_schema_compiler/test/tabs.json b/tools/json_schema_compiler/test/tabs.json index af0910a..d7271e6 100644 --- a/tools/json_schema_compiler/test/tabs.json +++ b/tools/json_schema_compiler/test/tabs.json @@ -1,6 +1,7 @@ [ { "namespace": "tabs", + "description": "The tabs API.", "types": [ { "id": "Tab", diff --git a/tools/json_schema_compiler/test/windows.json b/tools/json_schema_compiler/test/windows.json index f6062d4..ae90084 100644 --- a/tools/json_schema_compiler/test/windows.json +++ b/tools/json_schema_compiler/test/windows.json @@ -1,6 +1,7 @@ [ { "namespace": "windows", + "description": "The windows API.", "types": [ { "id": "Window", |