Skip to content
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 opened this issue Jun 6, 2016 · 0 comments

Comments

@evangalen
Copy link

evangalen commented Jun 6, 2016

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)

@Narretz Narretz added this to the Backlog milestone Jun 6, 2016
Narretz added a commit to Narretz/angular.js that referenced this issue Nov 29, 2016
Currently, ngdoc @method ignores @example tags. Examples are usually
rendered directly into the @description via code blocks or <example>
elements. However, some methods still have @example tags (possibly
from a previous docs version), which are currently not visible.

While not absolutely necessary, having special markup for Examples
makes them a) easier to find visually in the docs, and b) easier
to link to as they will have a unique id.

Closes angular#14722
Narretz added a commit to Narretz/angular.js that referenced this issue Nov 29, 2016
Currently, ngdoc `@method` ignores `@example` tags and does not output them.
This is usually not a problem, as examples are mostly defined directly
in the `@description` via code blocks or `<example>`
elements. However, some methods still have `@example` tags (possibly
from a previous docs version).

While not absolutely necessary, having special markup for Examples
makes them a) easier to find visually in the docs, and b) easier
to link to as they will have a unique id.

Closes angular#14722
@Narretz Narretz closed this as completed in f5d2bf3 Dec 1, 2016
Narretz added a commit that referenced this issue Dec 2, 2016
Currently, ngdoc `@method` ignores `@example` tags and does not output them.
This is usually not a problem, as examples are mostly defined directly
in the `@description` via code blocks or `<example>`
elements. However, some methods still have `@example` tags (possibly
from a previous docs version).

While not absolutely necessary, having special markup for Examples
makes them a) easier to find visually in the docs, and b) easier
to link to as they will have a unique id.

Closes #14722
Closes #15448
ellimist pushed a commit to ellimist/angular.js that referenced this issue Mar 15, 2017
Currently, ngdoc `@method` ignores `@example` tags and does not output them.
This is usually not a problem, as examples are mostly defined directly
in the `@description` via code blocks or `<example>`
elements. However, some methods still have `@example` tags (possibly
from a previous docs version).

While not absolutely necessary, having special markup for Examples
makes them a) easier to find visually in the docs, and b) easier
to link to as they will have a unique id.

Closes angular#14722
Closes angular#15448
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

2 participants