Good suggestion. Let's follow the style and remove the deprecated stuff in
2.x stream if possible.
Thanks,
Raymond
--------------------------------------------------
From: "Dan Becker" <[email protected]>
Sent: Friday, January 16, 2009 8:50 AM
To: <[email protected]>
Subject: [1.x] APIs and constructors marked deprecated - JavaDocs Suggestion
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
