[1.x] APIs and constructors marked deprecated - JavaDocs Suggestion

[Dan Becker]

Here's a helpful suggestion on deprecation and commenting in the source 
code. I see CompositeBuilderImpl has a number of constructors [1-4] with 
the first first 2 being marked deprecated and the second 2 not deprecated.

Does anyone have an idea on why these first 2 constructors were 
deprecated? (Rhetorical question, no need to answer here.) My guess is 
to use one of the newer, more fully featured constructors, perhaps with 
null params. However, it takes a bit of reading to tell.

I give a gentle reminder to people tagging APIs and constructors with 
@Deprecated (preferred) which should always be used with JavaDoc tag 
@deprecated. You should always document a short reason a give and a link 
to the newer preferred API. [5] Developers who do this will receive the 
highest nirvana. :-)

For example:
/**
 * @deprecated  As of Tuscany 1.blah we should be using the newer 
constructor which uses the preferred DocumentBuilderFactory and 
TransformerFactory, replaced by
 *              {...@link #CompositeBuilderImpl(AssemblyFactory, 
EndpointFactory, SCABindingFactory, IntentAttachPointTypeFactory, 
DocumentBuilderFactory, TransformerFactory, InterfaceContractMapper, 
SCADefinitions, Monitor)}
 */

References:
[1] CompositeBuilderImpl(AssemblyFactory, EndpointFactory, 
SCABindingFactory, IntentAttachPointTypeFactory, 
InterfaceContractMapper, SCADefinitions, Monitor)

[2] CompositeBuilderImpl(AssemblyFactory, SCABindingFactory, 
IntentAttachPointTypeFactory, InterfaceContractMapper, Monitor)

[3] CompositeBuilderImpl(AssemblyFactory, SCABindingFactory, 
IntentAttachPointTypeFactory, DocumentBuilderFactory, 
TransformerFactory, InterfaceContractMapper, Monitor)

[4] CompositeBuilderImpl(AssemblyFactory, EndpointFactory, 
SCABindingFactory, IntentAttachPointTypeFactory, DocumentBuilderFactory, 
TransformerFactory, InterfaceContractMapper, SCADefinitions, Monitor)

[5] 
http://java.sun.com/j2se/javadoc/writingdoccomments/index.ht...@deprecated
--
Thanks, Dan Becker