Remove spec links to source code
Azquelt opened this issue · 1 comments
Azquelt commented
In many places, the spec links directly to java files or markdown files stored in github source control.
This is not good for several reasons:
- Most of the links are to the
mainormasterbranch so the version of the linked document may no longer match the version of the spec. - Source code can be moved or refactored at any time, breaking the links.
There are several types of links in the spec and Javadoc:
- links to the OpenAPI spec markdown
- being updated in #607 to point to the hosted HTML version of the spec at https://spec.openapis.org/oas/v3.1.0.html
- links to the MP Config spec
- being updatd in #607 to point to the hosted HTML version of the spec at https://download.eclipse.org/microprofile/microprofile-config-3.1/microprofile-config-spec-3.1.html
- links to java files from MP OpenAPI
- ideally this would link to the Javadoc for the relevant class
- possible, but relies on knowing ahead of time where the Javadoc is going to be for releases
- not sure what the correct link would be when not building a release
- it might also be acceptable to link to the source code in github using the commit hash used for the build
- we could also consider removing the links
- most specs discuss classes in their API without linking to them
- ideally this would link to the Javadoc for the relevant class
Azquelt commented
Spotted a link to the rest client source: org.eclipse.microprofile.rest.client.inject.RegisterRestClient.