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(' */')