Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Ngdoc @example comments of all $provide service methods are not included in generated API docs #14722

Closed
@evangalen

Description

@evangalen

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)

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions