Ngdoc @example comments of all $provide service methods are not included in generated API docs #14722
Description
Do you want to request a feature or report a bug?
bug
What is the current behavior?
None of the @example
comment blocks of the methods of the $provide
service are included in the generated API documentation.
If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://plnkr.co or similar (template: http://plnkr.co/edit/tpl:yBpEi4).
Locally reproduced the bug by cloning the "angular.js" GitHub repo and after a grunt package
I had the same issue in my locally generated docs in ./build/docs
What is the expected behavior?
All of the methods of $provide
have a @example
comment and therefor each method should have a comment in the generated API docs.
To illustrate things I've included the jsdoc comment of $provide#value below:
/**
- @ngdoc method
- @name $provide#value
- @description
*- Register a value service with the {@link auto.$injector $injector}, such as a string, a
- number, an array, an object or a function. This is short for registering a service where its
- provider's
$get
property is a factory function that takes no arguments and returns the **value- service**. That also means it is not possible to inject other services into a value service.
*- Value services are similar to constant services, except that they cannot be injected into a
- module configuration function (see {@link angular.Module#config}) but they can be overridden by
- an Angular {@link auto.$provide#decorator decorator}.
*- @param {string} name The name of the instance.
- @param {*} value The value.
- @returns {Object} registered provider instance
*- @example
- Here are some examples of creating value services.
- $provide.value('ADMIN_USER', 'admin');
- $provide.value('RoleLookup', { admin: 0, writer: 1, reader: 2 });
- $provide.value('halfOf', function(value) {
return value / 2;
- });
*/
Unfortunately the nice example included in the jsdoc of .value
is not included in the generated API docs of the method: https://docs.angularjs.org/api/auto/service/$provide#value
What is the motivation / use case for changing the behavior?
It's a waste to not include those nice code examples in the generated API docs
Which versions of Angular, and which browser / OS are affected by this issue? Did this work in previous versions of Angular? Please also test with the latest stable and snapshot (https://code.angularjs.org/snapshot/) versions.
Checked both sources and API docs of latest 1.5, 1.4, 1.3 and 1.2 versions of AngularJS and all source-code had the @example
comments but for none of them it was included in the generated API docs.
Other information (e.g. stacktraces, related issues, suggestions how to fix)