search

osgi / bugzilla-archive

Archive of OSGi Alliance Specification Bugzilla bugs. The Specification Bugzilla system was decommissioned with the move to GitHub. The issues in this repository are imported from the Specification Bugzilla system for archival purposes.
0 stars 1 forks source link

[DS] Add links from javadoc back to specification #3014

Closed bjhargrave closed 4 years ago

bjhargrave commented 4 years ago

Original bug ID: BZ#3147 From: @cziegeler Reported version: R7

bjhargrave commented 4 years ago

Comment author: @cziegeler

It is useful to have links back from the javadocs of the annotations (and maybe api as well) back to the specification, for example when someone is using the @ Reference annotation and looks at the "bind" attribute, a link back to the chapter explaining the possible parameters for such a method etc.

bjhargrave commented 4 years ago

Comment author: @bjhargrave

What will the standalone javadoc look like?

You cannot make a relative link from the javadoc to the spec.

You also cannot make an absolute link since you hamstring our namespace.

Also, the javadoc for DS 1.5 (for example) must not be coupled to R8 (8.0.0/) since it can also be in R9 (9.0.0/) if we don’t change the DS spec for R9. We cannot be changing the spec release numbers on the javadoc source code for each release.

I don't think this is good idea.

bjhargrave commented 4 years ago

Comment author: @cziegeler

ok, resolving as won'T fix