def _generate_route(self, route_schema, namespace, route):
function_name = fmt_func(namespace.name + '_' + route.name)
self.emit()
self.emit('/**')
if route.doc:
self.emit_wrapped_text(self.process_doc(route.doc, self._docf),
prefix=' * ')
if self.args.class_name:
self.emit(' * @function {}#{}'.format(self.args.class_name,
function_name))
if route.deprecated:
self.emit(' * @deprecated')
self.emit(' * @arg {%s} arg - The request parameters.' %
fmt_type(route.arg_data_type))
self.emit(' * @returns {Promise.<%s, %s>}' % (fmt_type(
route.result_data_type), fmt_error_type(route.error_data_type)))
self.emit(' */')
self.emit('routes.%s = function (arg) {' % function_name)
with self.indent(dent=2):
url = '{}/{}'.format(namespace.name, route.name)
if route_schema.fields:
additional_args = []
for field in route_schema.fields:
additional_args.append(fmt_obj(route.attrs[field.name]))
self.emit("return this.request('{}', arg, {});".format(
url, ', '.join(additional_args)))
else:
self.emit('return this.request("%s", arg);' % url)
self.emit('};')
def _generate_route(self, route_schema, namespace, route):
function_name = fmt_func(namespace.name + '_' + route.name)
self.emit()
self.emit('/**')
if route.doc:
self.emit_wrapped_text(self.process_doc(route.doc, self._docf), prefix=' * ')
if self.args.class_name:
self.emit(' * @function {}#{}'.format(self.args.class_name,
function_name))
if route.deprecated:
self.emit(' * @deprecated')
self.emit(' * @arg {%s} arg - The request parameters.' %
fmt_type(route.arg_data_type))
self.emit(' * @returns {Promise.<%s, %s>}' %
(fmt_type(route.result_data_type),
fmt_error_type(route.error_data_type)))
self.emit(' */')
self.emit('routes.%s = function (arg) {' % function_name)
with self.indent(dent=2):
url = '{}/{}'.format(namespace.name, route.name)
if route_schema.fields:
additional_args = []
for field in route_schema.fields:
additional_args.append(fmt_obj(route.attrs[field.name]))
self.emit(
"return this.request('{}', arg, {});".format(
url, ', '.join(additional_args)))
else:
self.emit(
'return this.request("%s", arg);' % url)
self.emit('};')
def _generate_route(self, route_schema, namespace, route, extra_args):
function_name = fmt_func(namespace.name + '_' + route.name)
self.emit()
self.emit('/**')
if route.doc:
self.emit_wrapped_text(self.process_doc(route.doc, self._docf), prefix=' * ')
if self.args.class_name:
self.emit(' * @function {}#{}'.format(self.args.class_name,
function_name))
if route.deprecated:
self.emit(' * @deprecated')
self.emit(' * @arg {%s} arg - The request parameters.' %
fmt_type(route.arg_data_type))
if is_user_defined_type(route.arg_data_type):
for attr_key in route.attrs:
if attr_key not in extra_args:
continue
attr_val = route.attrs[attr_key]
if attr_val in extra_args[attr_key]:
arg_name, arg_type, arg_docstring = extra_args[attr_key][attr_val]
field_docstring = '@arg {%s} arg.%s' % (arg_type, arg_name)
if arg_docstring:
field_docstring += ' - %s' % arg_docstring
self.emit_wrapped_text(field_docstring, prefix=' * ')
for field in route.arg_data_type.all_fields:
field_doc = ' - ' + field.doc if field.doc else ''
field_type, nullable, _ = unwrap(field.data_type)
field_js_type = fmt_type(field_type)
if nullable:
field_js_type += '|null'
self.emit_wrapped_text(
'@arg {%s} arg.%s%s' %
(field_js_type, field.name,
self.process_doc(field_doc, self._docf)),
prefix=' * ')
self.emit(' * @returns {%s}' % fmt_type(route.result_data_type))
self.emit(' */')
self.emit('routes.%s = function (arg) {' % function_name)
with self.indent(dent=2):
url = '{}/{}'.format(namespace.name, route.name)
if route_schema.fields:
additional_args = []
for field in route_schema.fields:
additional_args.append(fmt_obj(route.attrs[field.name]))
self.emit(
"return this.request('{}', arg, {});".format(
url, ', '.join(additional_args)))
else:
self.emit(
'return this.request("%s", arg);' % url)
self.emit('};')
def _generate_union(self, union_type):
"""
Emits a JSDoc @typedef for a union type.
"""
union_name = fmt_type_name(union_type)
self._emit_jsdoc_header(union_type.doc)
self.emit(' * @typedef {Object} %s' % union_name)
variant_types = []
for variant in union_type.all_fields:
variant_types.append("'%s'" % variant.name)
variant_data_type, _, _ = unwrap(variant.data_type)
# Don't emit fields for void types.
if not is_void_type(variant_data_type):
variant_doc = ' - Available if .tag is %s.' % variant.name
if variant.doc:
variant_doc += ' ' + variant.doc
self.emit_wrapped_text(
'@property {%s} [%s]%s' % (
fmt_type(variant_data_type),
variant.name,
variant_doc,
),
prefix=' * ',
)
jsdoc_tag_union = fmt_jsdoc_union(variant_types)
self.emit(' * @property {%s} .tag - Tag identifying the union variant.' % jsdoc_tag_union)
self.emit(' */')
def _generate_struct(self, struct_type, extra_parameters=None, nameOverride=None):
"""
Emits a JSDoc @typedef for a struct.
"""
extra_parameters = extra_parameters if extra_parameters is not None else []
self._emit_jsdoc_header(struct_type.doc)
self.emit(
' * @typedef {Object} %s' % (
nameOverride if nameOverride else fmt_type_name(struct_type)
)
)
# Some structs can explicitly list their subtypes. These structs
# have a .tag field that indicate which subtype they are.
if struct_type.is_member_of_enumerated_subtypes_tree():
if struct_type.has_enumerated_subtypes():
# This struct is the parent to multiple subtypes.
# Determine all of the possible values of the .tag
# property.
tag_values = []
for tags, _ in struct_type.get_all_subtypes_with_tags():
for tag in tags:
tag_values.append('"%s"' % tag)
jsdoc_tag_union = fmt_jsdoc_union(tag_values)
txt = '@property {%s} .tag - Tag identifying the subtype variant.' % \
jsdoc_tag_union
self.emit_wrapped_text(txt)
else:
# This struct is a particular subtype. Find the applicable
# .tag value from the parent type, which may be an
# arbitrary number of steps up the inheritance hierarchy.
parent = struct_type.parent_type
while not parent.has_enumerated_subtypes():
parent = parent.parent_type
# parent now contains the closest parent type in the
# inheritance hierarchy that has enumerated subtypes.
# Determine which subtype this is.
for subtype in parent.get_enumerated_subtypes():
if subtype.data_type == struct_type:
txt = '@property {\'%s\'} [.tag] - Tag identifying ' \
'this subtype variant. This field is only ' \
'present when needed to discriminate ' \
'between multiple possible subtypes.' % \
subtype.name
self.emit_wrapped_text(txt)
break
for param_name, param_type, param_docstring in extra_parameters:
param_docstring = ' - %s' % param_docstring if param_docstring else ''
self.emit_wrapped_text(
'@property {%s} %s%s' % (
param_type,
param_name,
param_docstring,
),
prefix=' * ',
)
# NOTE: JSDoc @typedef does not support inheritance. Using @class would be inappropriate,
# since these are not nominal types backed by a constructor. Thus, we emit all_fields,
# which includes fields on parent types.
for field in struct_type.all_fields:
field_doc = ' - ' + field.doc if field.doc else ''
field_type, nullable, _ = unwrap(field.data_type)
field_js_type = fmt_type(field_type)
# Translate nullable types into optional properties.
field_name = '[' + field.name + ']' if nullable else field.name
self.emit_wrapped_text(
'@property {%s} %s%s' % (
field_js_type,
field_name,
self.process_doc(field_doc, self._docf),
),
prefix=' * ',
)
self.emit(' */')