By default, the acronyms refer to the JCP specs. We only need the
"disclaimer" when we want to use the acronyms to refer to Jakarta EE
specs.
So, I think we can leave the @since entries as they are, referring
to the JCP specs, and then in the future use the Jakarta spec name
in new @since entries.
(Note that this only works if the spec hasn't already included the
disclaimer so that the acronym refers to the Jakarta EE spec. In
that case it's a bit weird to use the acronym referring to the
Jakarta EE spec along with a version number that predates the
Jakarta EE spec, but that may be an acceptable compromise.)
Scott Stark wrote on 7/16/19 2:10 PM:
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
_______________________________________________
jakartaee-spec-project-leads mailing list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
|