| For this Jakarta EE 8 release there are no new @since annotations. Can we just add statements at the top of each spec javadoc index that indicates all acronyms in this release refer to the Java EE 8 terms in use under the JCP x.y?
Then as new specs evolve, they can use the full Jakarta spec short name in any @since.
Just to remind everyone, most developers just look at the platform
javadocs. When some average developer is looking at some random API
in the Jakarta EE 10 platform javadocs and sees "@since 1.1", how
are they expected to interpret that? The best solution would be to
use the platform version number, but that doesn't work when looking
at an individual API's javadocs. If the number can't be relative to
the javadocs they're looking at, the next best seemed to be to
qualify the number in some way with the name of the spec it refers
to.
Expecting that average developers will trace their way up the
package tree until they find something that tells them what spec the
number refers to seems like too much to me.
Emily Jiang wrote on 7/16/19 9:05 AM:
+1 on option 1 as it still stands correct.
Emily
Perhaps we can have something like "@Since
Java Transaction API 1.1 (TM/copyright Oracle?)"
For now my PR was approved and merged to
remove the name entirely. I (personally) don't
find that too confusing or at least no more
confusing that referencing a non-existent
Jakarta Transactions 1.1. That said, I would be
happy to raise a new PR with any naming
convention the community decides. I see the
following options:
1. @Since 1.1
2. @Since (some agreed way of referencing old
JCP spec name) 1.1
3. @Since (new Jakarta spec name) 1.1
4. Remove @Since entirely
Whatever option we go for though I would hope
that all specs will follow the same convention.
I would be in favour of option 1. with the
addition of whatever metadata (spec name &
version) could be added in javadoc via
package-info.java
- Ray
The reason the spec name
was included is because when all the javadocs
are combined to form the platform javadocs,
it's much less clear what spec "1.1" refers
to.
Using a Jakarta spec name in @since can be
misleading or wrong since we didn't have old
versions of the Jakarta specs. Still, I think
that's better than dropping the spec name
entirely and introducing the ambiguity.
Scott
Stark wrote on 7/15/19 11:42 AM:
The most common
things seems to be to simply drop the
reference to the spec
@since Common Annotations 1.1 ->
@since 1.1
How do we handle "@since"
tags?
For example:
> * @since Common
Annotations 1.1
I'm guessing we leave them
but I wanted to make sure.
- Ray
|
