Improve JavaDoc for junit-platform-suite-api annotations

[smoyer64]

Overview

With the adoption of a declarative suite mechanism in JUnit 5 proposed in #744, the annotations that were moved to the junit-platform-suite-api will be used more broadly than for test selection using the JUnit 4 JUnitPlatform runner.

Original Proposal

• The javadocs for these annotations should be changed to describe their meaning without reference to this runner.
• Make the javadocs for the junit-platform-suite-api annotations consistent with their expanded use.

Deliverables

Consider improving the JavaDoc for each of the following suite API annotations in order to better explain their generic purpose vs. usage with the JUnitPlatform runner for JUnit 4.

• ExcludeClassNamePatterns
• ExcludeEngines
• ExcludePackages
• ExcludeTags
• IncludeClassNamePatterns
• IncludeEngines
• IncludePackages
• IncludeTags
• SelectClasses
• SelectPackages
• UseTechnicalNames

[Andrei94]

@smoyer64 could you please assign the issue to me? I don't have access to this feature.

[smoyer64]

@Andrei94 I can not ... but perhaps one of the @junit-team/junit-lambda members will mark it up-for-grabs and assign it to you.

[Andrei94]

so then if I want to work for it how should I do it?

[smoyer64]

@Andrei94 I should have been more clear ... I'm not a member of the core team so I can't assign issues.

In general, I find that the team is pretty happy to accept pull requests for tasks like this (javadocs and documentation don't tend to have architectural implications). If you fork the project, make the changes and submit a PR without having the issue assigned to you the only real risk is that someone else might also work on the task.

In my last response, it appears that I can't invoke the team as a group - perhaps @sormuras, @marcphilipp or @sbrannen will chime in with an official opinion.

[Andrei94]

Ok @smoyer64 Thank you very much for the clarification. I already forked the project. 😃

[sbrannen]

We have no intention of removing references to the JUnit 4 suite support on the platform.

That's why I deliberately added a new JUnit 4 Suite Support as the last section of the JavaDoc for each of those annotations.

If/when we introduce generic suite support (either in the Platform or in Jupiter), we will also reference those implementations from the suite API annotations.

Having said that, if you think the current wording is confusing or misleading, we are open to suggestions.

Cheers,

Sam

[smoyer64]

Well ... clearly the wording was confusing to me! On the other hand, now that I've reread the javadocs and noted the JUnit 4 Suite Support heading above the reference to JUnit 4 and the JUnitPlatform runner I'm not sure. Since these annotations are part of an API, we can't possibly list out all the implementations that are created. On the other hand, I think it's worth referencing the built-in suites (plural assuming something like what's described in #744 is adopted).

I'm tempted to close this issue but let's leave it open and see whether anyone has suggestions for changes.

As an aside, I'm sorry I didn't look at the commit that changed the javadocs when the annotations were moved into junit-platform-suite-api ... I should have noticed that you'd thought through what was included.

[sbrannen]

Since these annotations are part of an API, we can't possibly list out all the implementations that are created. On the other hand, I think it's worth referencing the built-in suites (plural assuming something like what's described in #744 is adopted).

My sentiments exactly! 😉

[sbrannen]

I'm tempted to close this issue but let's leave it open and see whether anyone has suggestions for changes.

Sure.

And... BTW, I'll most certainly revise the JavaDoc for the entire suite API once we have built-in support in the Platform (other than the current JUnit 4 support).

[sbrannen]

As an aside, I'm sorry I didn't look at the commit that changed the javadocs when the annotations were moved into junit-platform-suite-api ... I should have noticed that you'd thought through what was included.

No worries. I do my best to think things through, though I don't always succeed. ☺️

[sbrannen]

I'm modifying the title and description of this issue accordingly.

[sbrannen]

Additional polish has been applied in recent commits and most recently in 5810cf6.

Since no one has chimed in with further enhancement requests for the current JavaDoc, I am closing this issue.

Further refinements will be performed in conjunction with #744.

[michaelajr]

Any news on when the suite-api annotations will be supported in JUnit5 proper (platform, engine)? Would be great to have these work without the need to use the JUnit4 runner.

[sbrannen]

This issue is closed.

The issue that will introduce support for declarative test suites (#744) is currently slated for 5.1 M2.