docs(misc core): @function and @kind function used inconsistently. Use @kind function.

[wesalvaro]

Request Type: docs

Component(s): misc core

Impact: small

Complexity: small

Detailed Description:

@kind function should be used in lieu of @function.
Switch to use @kind function everywhere.

[mary-poppins]

Thanks for the PR! Please check the items below to help us merge this faster. See the contributing docs for more information.

• Uses the issue template (#7425)

If you need to make changes to your pull request, you can update the commit with git commit --amend.
Then, update the pull request with git push -f.

Thanks again for your help!

[wesalvaro]

... Although I couldn't find @function on the JSDoc site (http://usejsdoc.org/index.html), it is used heavily. Where is more information about how JSDoc is used in AngularJS?

[Narretz]

Angular uses https://github.com/angular/dgeni to generate its documentation. I guess might find some answers there. Maybe @function is not a real JSDoc annotation in this respect.

[mary-poppins]

I'm sorry, but I wasn't able to verify your Contributor License Agreement (CLA) signature. CLA signature is required for any code contributions to AngularJS.

Please sign our CLA and ensure that the CLA signature email address and the email address in this PR's commits match.

If you signed the CLA as a corporation, please let us know the company's name.

Thanks a bunch!

PS: If you signed the CLA in the past then most likely the email addresses don't match. Please sign the CLA again or update the email address in the commit of this PR.
PS2: If you are a Googler, please sign the CLA as well to simplify the CLA verification process.

[mary-poppins]

CLA signature verified! Thank you!

Someone from the team will now triage your PR and it will be processed based on the determined priority (doc updates and fixes with tests are prioritized over other changes).

[btford]

@petebacondarwin thoughts?

[petebacondarwin]

@btford - let me just remind myself of when those are used in Dgeni!

[petebacondarwin]

OK, so actually we rely on the @kind tag in our doc generation and totally ignore the @function tag. It is only relevant where we want to be able to tell the difference between a service that is an object and a service that is also callable (i.e. a function).

See https://github.com/angular/dgeni-packages/blob/master/ngdoc/templates/api/object.template.html#L6

[petebacondarwin]

Moreover, @function is from JSDOC 2 and @kind is from JSDOC 3. So I suggest that we can indeed consolidate but use @kind function instead.

@wesalvaro - can you update your PR in this respect?

[wesalvaro]

Hahaha! That was actually my first revision, but I changed it because I figured you guys had a secret version you were using given how much it was used. I'll revert back to the @kind version. =P

[wesalvaro]

Updated.

[wesalvaro]

Tests are flaky. This is ready for review/merge.

[caitp]

LGTM, the travis failures are flakes

[caitp]

@petebacondarwin I'll leave this up to you to merge, but it doesn't look like it causes any problems

[petebacondarwin]

You know what, looking at this further. The only place where it makes any difference using @kind is when you have @ngdoc service. For all the other instances, it is self evident from the @ngdoc tag what the kind of thing it is. I suggest therefore that we actually remove both the @function and @kind tags from all docs except @service. @wesalvaro and @caitp what do you think?

Further, it now occurs to me that @ngdoc object and @ngdoc function are a waste of space. Instead we ought to use a new docType @ngdoc global and then use the same logic as is used in @ngdoc service to work out whether the thing is an object or a function. Again, @wesalvaro and @caitp what do you think?

[petebacondarwin]

Landed for now as aa26856