[weld-issues] [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
[
https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.s...
]
Ondrej Zizka commented on WELD-900:
-----------------------------------
{quote}
2.1.5. Interceptor binding types
You might be familiar with the use of interceptors in EJB 3.0. In Java EE 6, this
functionality has been generalized to work with other managed beans. That's right, you
no longer have to make your bean an EJB just to intercept its methods. Holler. So what
does CDI have to offer above and beyond that? Well, quite a lot actually. Let's cover
some background.
{quote}
I don't think that assuming all readers are familiar with the use of interceptors.
The concept should be shortly explained, and maybe there can be a note that it originated
in EJB 3.0.
Truth is, that it's covered that way in the chapter 9, but even in the introduction,
I'd keep it that way.
Docs: Improve Weld reference. Make it less poetic and more
structured.
----------------------------------------------------------------------
Key: WELD-900
URL: https://issues.jboss.org/browse/WELD-900
Project: Weld
Issue Type: Bug
Components: Documentation
Reporter: Ondrej Zizka
Assignee: Pete Muir
It's nice to have a nice text for a DZone article, but for a reference documentation,
we should favor briefness and structure over potential nomination for Man Booker
International Prize :)
What I mean is, e.g., if someone starts with Weld, he needs steps 1., 2., 3.
IMO, this should be in **bold** in a special chapter called "Preparing project to
use Weld", with a sample code which is verified to work if copied and run, and
eventually a reference to a quick-start app:
{quote}
There's just little one thing you need to do before you can start injecting them into
stuff: you need to put them in an archive (a jar, or a Java EE module such as a war or EJB
jar) that contains a special marker file: META-INF/beans.xml.
{quote}
In contrast, currently this most important information is buried at the end of last
paragraph of irrelevantly sounding chapter, "1.1. What is a bean?". Why would
anyone read "What is a bean"?
my2p, ymmv
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira