You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by Dan Becker <da...@gmail.com> on 2009/01/16 17:50:09 UTC
[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.html#@deprecated
--
Thanks, Dan Becker
Re: [1.x] APIs and constructors marked deprecated - JavaDocs Suggestion
Posted by Raymond Feng <en...@gmail.com>.
Good suggestion. Let's follow the style and remove the deprecated stuff in
2.x stream if possible.
Thanks,
Raymond
--------------------------------------------------
From: "Dan Becker" <da...@gmail.com>
Sent: Friday, January 16, 2009 8:50 AM
To: <de...@tuscany.apache.org>
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.html#@deprecated
> --
> Thanks, Dan Becker