[ https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12604831#comment-12604831 ]
Ondrej Zizka commented on WELD-900:
-----------------------------------
May I put some notes about what I meant? Not necessarily reopening the issue.
For instance, "1.2. Getting our feet wet".
1) Call me boring, but in reference manual, I'd expect "CDI Basics" or such.
2)
{quote}
But wait! TextTranslator does not have a constructor with no parameters! Is it still a bean? If you remember, a class that does not have a constructor with no parameters can still be a bean if it has a constructor annotated @Inject.
As you've guessed, the @Inject annotation has something to do with dependency injection!
{quote}
As I wrote - such stile is fine for an article or a book.
But I'd expect a reference to be concisee. Sencences as "But wait", "Is it still a bean?", "If you remember", "As you've guessed" and such are just distracting. I'd rather welcome terse facts.
3) Example
{code}
@Named @RequestScoped \
public class TranslateController
{code}
If this is "Getting started" guide, then it should assume uninitiated reader.
a) @Named should eitner not be present since it's not related to the matter being explained.
b) @RequestScoped should explained shortly - 1 sentence with a link to list of related annotations.
I hope I explained what I meant by this jira.
> 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