jakartaee / jakartaee/inject

Javadoc for @Named is misleading to users of CDI

Open
#33 6 comments 1 reaction 0 assignees View on GitHub
Dominant language
Java
Stars
27
Forks
19
PR merge metrics
No merged PRs in 30d

Description

**Is your feature request related to a problem? Please describe.**
The CDI specification [recommends that `@Named` is not used as a qualifier at injection points](https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#named_at_injection_point). However, the [Javadoc for `@Named`](https://jakarta.ee/specifications/dependency-injection/2.0/apidocs/jakarta/inject/named) merely says that it's a string based qualifier and gives an example of it's use in this context.

CDI uses `@Named` to assign a bean name for lookup from technologies like JSF. Bean names mostly have to be unique among the application.

**Describe the solution you'd like**
Can we add a note to the `@Named` annotation indicating that CDI recommends against its use as a qualifier for injection points?

**Describe alternatives you've considered**
We could just remove the example showing `@Named` used in the way that CDI recommends against.

We could do nothing and acknowledge that the choice to have shared injection annotations means that the Javadoc can't be as helpful to users as we'd like.

**Additional context**
I realise that there are other consumers of `@Named` other than CDI (I'm aware of Spring and Guice). Any guidance for use in CDI would have to be written in a way that doesn't mislead users of these technologies.

Contributor guide

Open the contributing guide

Research direction

Start by reading the Javadoc for the @Named annotation and the linked CDI specification guidance. Decide whether a CDI-specific note or removal of the injection-point example best avoids misleading users of Spring and Guice; done means the Javadoc clearly explains the CDI concern without overstating it.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.