No support for @typedef / @callback?

[reloaded]

Appears there's no support for using the @typedefand @callback (I think internally @callback piggybacks off @typedef. http://usejsdoc.org/tags-callback.html

  /**
   * Called when a location is selected from the list of results and passed the location object.
   *
   * @callback Simpl.Directives.Widgets.Location.LocationSearch~onLocationSelect
   * @param {Simpl.Entities.Location} The selected location.
   */

  /**
   * Triggers a new "Location Search" modal to open on element click. Parent scopes can receive the selected location
   * through the <code>on-location-select</code> and/or <code>selected-location</code> bindings.
   *
   * @ngdoc directive
   * @alias Simpl.Directives.Widgets.Location.LocationSearch
   * @scope object
   * @restrict A
   * @attr {Expression} selectedLocation An expression that receives the selected location object.
   * @attr {Simpl.Directives.Widgets.Location.LocationSearch~onLocationSelect} onLocationSelect A callback that receives the selected location object.
   * @example
   * <a simpl-location-search
   *    on-location-select="MyCtrl.OnLocationSelected"
   *    class="btn btn-link"
   *    role="button"></a>
   */

The result of the directive documentation page is below.

It looks accurate at first glance, but when you click on the onLocationSelect type link it redirects to a URL that looks accurate, but no HTML file was generated for the @callback Simpl.Directives.Widgets.Location.LocationSearch~onLocationSelect doc block.

JSDOC3 is generating object structures for the callback doc block.

[allenhwkim]

No, I haven't implemented @callback and @typedef into html yet. PR would be appreciated.

[Zemke]

In what ways is @typedef different from @ngdoc type?

[reloaded]

@Zemke http://usejsdoc.org/tags-typedef.html

@ngdoc and @typedef have different purposes. One is to classify a docblock as a directive/controller/module/filter and one is to create virtual custom types.

[Zemke]

There’s a value of type for @ngdoc like you’d use @ngdoc directive, you can use @ngdoc type which is supported by angular-jsdoc and which also meets your definition of @typedef and also the one of JSDoc:

The @typedef tag is useful for documenting custom types, particularly if you wish to refer to them repeatedly. These types can then be used within other tags expecting a type, such as @type or @param.

I use @ngdoc type heavily in one of my projects and we’ve used @typedef before.

[reloaded]

I understand that @ngdoc provides a custom "type" value, but considering that angular-jsdoc is built off of JSDOC we should support the JSDOC tags.

[Zemke]

Well, ngDoc is a flavor of JSDoc, so that’s actually not a “choice” as such.

But back to my question: What are the differences gof @ngdoc type and @typedef? I’m just wondering how we’d separate them in the generated documentation. I don’t see a feasible way of a co-exsitence of them.

[reloaded]

I can not find any documentation on @ngdoc type. Can you link me to documentation where the Angular team has explained the usage of @ngdoc type.

https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation#the-ngdoc-directive

[Zemke]

Actually I can’t. Resources seem very rare on that. An example would look like this.

/**
 * @ngdoc type
 * @name ExampleType
 * @memberof app
 *
 * @description
 * This is a type created for exemplary purposes
 * 
 * @property {string} exampleProp This is a string  property in our custom type.
 * @property {app.AnotherCustomType} propertyName You can create whole trees of custom types.

[reloaded]

My opinion is if angular-jsdoc is based off of jsdoc then all jsdoc tags should be supported to provide maximum flexibility to the users.

Jsdoc typedef has documentation supporting it's usage.

ngdoc type doesn't