search

angular / dgeni

Flexible JavaScript documentation generator used by AngularJS, Protractor and other JS projects
MIT License
769 stars 68 forks source link

Requiring @name property causes IDE bugs #112

Open btesser opened 9 years ago

btesser commented 9 years ago

This is related to the fact that in the jsdoc standard, the @name property causes the parser to ignore the context that the item exists in. Here's a snippet from the jsdoc3 docs:

The @name tag forces JSDoc to associate the remainder of the JSDoc comment with the given name, ignoring all surrounding code - http://usejsdoc.org/tags-name.html

This causes issues in Webstorm, Phpstorm, Intelli-j, etc. which try to parse the jsdoc comment blocks. In particular, it is unable to locate methods on objects, properties, types, autocomplete, etc. The issues are fairly invasive. When the @name property is removed, this work perfectly fine.

I've come up with a few workarounds that help, but are all hacky.

  1. Prefixing the name with a colon (:) causes the ide to treat the item being documented differently, and recognizes the method better, but still not perfectly. For example:
/**
  * @ngdoc method
  * @name :myMethod
  */
  1. After the dgeni/ngdocs comment block add an additional /**/. This causes the name not to apply to the code below it, but then you lose the ide support of whatever type annotations and doc completion that was added. For example:
/**
 * @ngdoc method
 * @name myMethod
 *//**/

3, A combination of 1, 2, or both and adding the @class tag with the name as the value. This helps the idea recognize that it is related somewhat.

You may feel that this is not an issue in dgeni, but since dgeni has a jsdoc package, and it is generally in line with the jsdoc standard, I believe that requiring a tag in an unorthodox way that breaks other jsdoc tools which conform to the standard is in fact an issue.

My suggested fix for this is to allow the use of an alias for name that would not get picked up by other tools... perhaps @dname or something like that (for dgeni-name)

Let me know your thoughts... I hope you take this seriously. This issue has been a major stumbling block for me as I find the IDE tools extremely valuable. This has also caused issues in code review with people asking why my hacky fixes are in there, etc.

petebacondarwin commented 9 years ago

@btesser - thanks for the issue. Is your problem when working with the Angular.js source code or your own code?

btesser commented 9 years ago

both

petebacondarwin commented 9 years ago

How about we follow the suggestion in the jsdoc docs, which is to use @alias instead of @name?

btesser commented 9 years ago

That looks like a reasonable solution. I'll read up on alias to make sure there aren't any side effects, but that would be awesome :). I use dgeni with the angular package to document projects at my place of business

petebacondarwin commented 9 years ago

With the angular package? Is that the one inside the angular.js project source code? You might be interested in having a play with (or helping out with) my new package, angularjs. See https://github.com/petebacondarwin/dgeni-angular and https://github.com/angular/dgeni-packages/tree/angular-docs

btesser commented 9 years ago

Definitely I'll check it out (and see if I'm able to help...though it's hard to find the time). By the way I tried alias in my ide.... problem is 100% fixed!

petebacondarwin commented 9 years ago

So we probably just need to tweak ngdocs to make @alias effectively equivalent to @name in terms of setting the name of a doc.

btesser commented 9 years ago

Ok I'm a bit confused looking at the source of https://github.com/petebacondarwin/dgeni-angular. There seems to be very few ngdocs annotations (or even jsdoc annotations). Has dgeni improved so it is parsing the code as well as the doc blocks now, or is it just incomplete.

btesser commented 9 years ago

Does dgeni parse the code as well as the docs... or just the docs. Because if it is parsing the code as well, technically, @name should make it ignore the code and just focus on the docs for that segment. I don't feel strongly that that behavior has to match jsdocs, but if we wanted to go with the standard, I believe that's what would happen

petebacondarwin commented 9 years ago

It is attempting to parse the code!!

btesser commented 9 years ago

Awesome... to what extent can that be relied on?

gampleman commented 9 years ago

@petebacondarwin when can we expect that to be released? Looks very interesting!

petebacondarwin commented 9 years ago

Soon as I can get it working properly. :-) Do go to https://github.com/petebacondarwin/dgeni-angular and see if you can get it to work. Post issues and suggest fixes