kieker-monitoring / kieker

Kieker's main repository
Apache License 2.0
70 stars 41 forks source link

[KIEKER-595] Add missing @since tags to the javadoc #1094

Open rju opened 2 weeks ago

rju commented 2 weeks ago

JIRA Issue: KIEKER-595 Add missing @since tags to the javadoc Original Reporter: Nils Christian Ehmke


See KIEKER-680 Done . We should at least add the @since tag to the methods newly introduced in 1.7.

Checklist:

rju commented 2 weeks ago

author André van Hoorn -- Mon, 25 Feb 2013 18:05:08 +0100

OK, we should find an agreement about whether we do this on method level ... I was thinking about class level. But method level might make sense for interface methods; I not sure.

rju commented 2 weeks ago

author nils-christian -- Mon, 25 Feb 2013 18:06:25 +0100

Classes, Interfaces, Annotations and all methods within interfaces would be my suggestion.

rju commented 2 weeks ago

author Jan Waller -- Mon, 25 Feb 2013 18:20:00 +0100

Sounds good. We should also remove tags not in the chosen categories.

rju commented 2 weeks ago

author André van Hoorn -- Mon, 25 Feb 2013 18:47:10 +0100

Replying to [jwa|comment:4]:
> Sounds good. We should also remove tags not in the chosen categories.

agree

rju commented 2 weeks ago

author nils-christian -- Mon, 25 Feb 2013 21:00:35 +0100

Replying to [jwa|comment:4]:
> Sounds good. We should also remove tags not in the chosen categories.

This part has been done in 51e43989ad0ea3cbf1311d8b40c98c649c332bc0.

rju commented 2 weeks ago

author nils-christian -- Mon, 25 Feb 2013 21:10:58 +0100

All classes which have been added since the 1.6 tag have been marked in f17879d5694cc352db3c2f1f450dad804730353a. I check whether I can add the tags for 1.6 as well with reasonable effort, but I think the ticket can be closed.

rju commented 2 weeks ago

author nils-christian -- Mon, 25 Feb 2013 22:07:52 +0100

With 3e511c8bdf75779e72995c060d58245df37a7b4c the necessary 1.6 tags should be there.

rju commented 2 weeks ago

author Jan Waller -- Fri, 8 Mar 2013 17:41:52 +0100

Nils Christian Ehmke: Do you have an automated script to check this?
I can guarantee, that I forgot it most of the time with my last checkins.

So correct usage (not too much, not too few) should be checked again before the release.

rju commented 2 weeks ago

author nils-christian -- Fri, 8 Mar 2013 22:35:29 +0100

I don't have a script currently, as I ran manually through the code the last time. But I guess I could either write one or another checkstyle check. The latter is probably better. I imagine something like the following:

since tag exists <=> element is either a class, an interface, an annotation or a method within an interface

rju commented 2 weeks ago

author Jan Waller -- Fri, 8 Mar 2013 22:51:56 +0100

Replying to [nie|comment:10]:
> I don't have a script currently, as I ran manually through the code the last time. But I guess I could either write one or another checkstyle check. The latter is probably better. I imagine something like the following:
>
> since tag exists <=> element is either a class, an interface, an annotation or a method within an interface
or just very old

rju commented 2 weeks ago

author nils-christian -- Fri, 8 Mar 2013 23:21:44 +0100

Replying to [jwa|comment:11]:
> or just very old

Good point. Possible solutions:

rju commented 2 weeks ago

author nils-christian -- Sat, 9 Mar 2013 16:57:25 +0100

I introduced a new check with 7eb469e7c48602f038885082879a757d3deef328. The current version checks only in one direction, as the visitor pattern of CS doesn't support javadoc directly (That means: Missing since tags are reported
- but not the not allowed tags).

rju commented 2 weeks ago

author nils-christian -- Sat, 9 Mar 2013 17:20:16 +0100

I introduced a second test in 7457919d717c943a1d0f6147d52bbb1fda1f0af9 checking the other direction.

I will try and remove the invalid tags before adding as much missing tags as possible.

rju commented 2 weeks ago

author nils-christian -- Fri, 15 Mar 2013 10:39:26 +0100

I think most of the classes from 1.5, 1.6 and 1.7 have been tagged. Tagging the remaining classes is difficult, because one has to backtrace the first introduction for each of them. I will try to add some more tags, but I think the ticket can be closed.

rju commented 2 weeks ago

author nils-christian -- Wed, 20 Mar 2013 20:28:47 +0100

Okay, now we need a solution for the remaining classes. The build fails due to too many warnings.

rju commented 2 weeks ago

author nils-christian -- Fri, 22 Mar 2013 10:55:00 +0100

With 7f595f1669def071bfa3ec1435c688e648bcd64f I modified the test
- It doesn't check the since tag for private classes/interfaces etc. The since tag is only important for the public API, I guess.

rju commented 2 weeks ago

author nils-christian -- Sat, 23 Mar 2013 21:46:30 +0100

With b50b9cfee39a8c7855380695f5d5bc050f22b9e8 all tags should be there. It was difficult to trace back some of the real old classes, but I think all in all it should be quite accurate.