Add javadoc comments

[sadikovi]

This PR adds javadoc comments to language-java: @author, @deprecated, @exception, @return, @see, @serial, @since, @throws, @version, @param, and @link, mentioned in issue #54. I tried adding highlighting for embedded code snippet in javadoc comments, but could not make it work.

Used language-scala package mainly for guidance and implementation, since Atom packages are new to me.

Here is what it looks like in Atom:

Testing

Updated existing tokenizes enum test, added unit-tests.

[sadikovi]

@50Wliu @noseglid please review.

[noseglid]

Possibly have contentName: meta.comment.body.java for consistency with class bodies, method bodies, try-catch-finally bodies etc.

[sadikovi]

I guess I should replace 'name': 'comment.block.java' with 'contentName': 'meta.comment.body.java' in the whole comments-inline, right?

[sadikovi]

I mean only for line 470 and line 510.

[noseglid]

I believe the name is correct (the tags /** and */ will get name). If you add contentName then the content will get that name - which is the body of the comment. What do you think, @50Wliu ?

[winstliu]

Since this is a Javadoc comment, would changing name to be comment.block.javadoc.java suffice? Do you think there would still be a benefit to having a separate contentName?

[noseglid]

Changing to comment.block.javadoc.java would work well I think

[noseglid]

Javadoc comments should only be in the class (enum,interface etc) body, right? As it is now it also tags javadoc such as:

class Test {
  public static void main(String[] args) {
    /**
     * @throws somethingElse
     */
  }
}

Which may not be what we want.

[noseglid]

After #something there can be a label. This will be tagged with the variable.parameter.java which is probably not correct. Adding that to the specs would be nice too

[sadikovi]

@noseglid Yeah, you are right about javadoc inside method, this "feature" seems to also exist in language-scala:). I am not sure how to fix it, to be honest. Do you know, if I can extract information if javadoc is inside method body somehow?

[sadikovi]

Well, I will think about how to possibly fix javadoc-inside-method-body issue.

[noseglid]

I think I would create a javadoc pattern, and only include it in the class-body or the "root" (for javadocing classes).

Great job on the PR btw, looks great overall, and very nice to get the Javadoc tagged properly!

[winstliu]

Please make this a separate beginCaptures and endCaptures.

[winstliu]

I tried adding highlighting for embedded code snippet in javadoc comments, but could not make it work.

Can you give an example of an embedded code snippet? I might have some ideas for how to highlight that.

Also left some minor style comments :).

[sadikovi]

Thank you @noseglid @50Wliu, I will address comments later today. It seems like my first approach was suboptimal, I should have created a separate pattern for it.

[sadikovi]

@50Wliu It is usually done using {@code ... }, can be multi-line, I do not really use this feature, I am not sure how often people use it (I know that you can use <code></code> instead), but generally it is like this:

/**
 * Usage:
 * {@code
 * int s = getSomething();
 * boolean a = s > 1;
 * }
 */
public static int getSomething() {
  return -1;
}

When I was trying it, I could not make it to treat * on every line as a beginning of a comment.
Anyway, I will refactor code as @noseglid suggested, this should make it easier to try fixing this.

I guess,

[winstliu]

Hmm yeah, that'll be tricky. When I have time I'll pull down this branch and see if I can figure out something that works.

[sadikovi]

@noseglid @50Wliu I addressed your comments, added comments-javadoc pattern that is applied inside class-body and at root level only, there is a test for comment inside the method.

I am a little bit confused with:

'name': 'comment.block.javadoc.java'
'contentName': 'meta.comment.block.javadoc.java'

Should I keep it this way, or should I change it to:

'name': 'meta.comment.javadoc.java'
'contentName': 'meta.comment.javadoc.body.java'

similar to class and method, or any other way?

Have not tried multi-line {@code ...}, and honestly, I do not think it is very essential to add that.

[noseglid]

I think you should remove contentName leaving only name: 'comment.block.javadoc.java'.

Other than that this looks nice, I think.

[sadikovi]

Ok, will do, thanks.

[sadikovi]

@50Wliu @noseglid Rebased PR. Could you review it again, please?

[noseglid]

LGTM 👍

[sadikovi]

@50Wliu can you have a look at the PR?

[winstliu]

Been busy but I'll probably have some free time over the weekend or next week.

[winstliu]

Very small nit: the { and } don't need to be escaped.

[sadikovi]

@50Wliu I addressed your comments, would you mind taking a look again?

[winstliu]

Thanks!

[sadikovi]

@50Wliu @noseglid Thank you very much for reviewing and merging pull request!