Function completion chooses the wrong doc

[mrennie]

Paste the following snippet in the Tern demo page and activate assist on the 'f' as indicated:

/* eslint-disable no-eval, no-unused-params, no-unused-vars /
/*

• @name f
• @param {Number} one the first one
• @param {orion.Editor} two
  */
  function f(one, two, three) {
  loop: do{
  f//ASSIST HERE
  //empty
  continue loop;
  } while(true)
  }

If you check the proposal it shows the doc for the eslint directive, not the JSDoc for the function

[marijnh]

Yes, the doc processor can't read human language, so it doesn't know which comment best summarizes the function. I don't think always picking the one with JSDoc directives is a great solution -- in your example it is entirely useless as well.

[mrennie]

Perhaps it would be best to always choose the doc closest to the element when more than one provided.

See plugin/doc_comment.js ~line 96, the first comment is always chosen, maybe something like

var first = comments[comments.length-1]

would be accurate more often when > 1 comments are before a node

[marijnh]

The current strategy depends on the assumption that if there are more than one comment on top of a function, they all refer to the function, and thus the top one is most likely to start with the actual description of the function's role. I realize that this doesn't always hold, but in my experience it is more often accurate than choosing the last comment would be.

[mrennie]

Perhaps then we could add some improved logic to weed out any proceeding comments that do not have any JSDoc tags of interest to Tern? So in my given example the first comment would be ignored since it has no JSDoc tags at all.

[marijnh]

Many doc comments don't have JSDoc tags. I don't see any value in using the @name/@param junk from your example as docstring either, it doesn't tell you anything about the function that the type signature doesn't already say.

I'm sure the way Tern picks docstring comments can be improved, but I'm not going to make random changes to address specific use cases.