[weld-issues] [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.

Ondrej Zizka (JIRA) jira-events at lists.jboss.org
Thu May 26 20:58:01 EDT 2011

    [ 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.
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!

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 
@Named @RequestScoped \
public class TranslateController

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


More information about the weld-issues mailing list