Re: [all] svn commit: r669887

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [all] svn commit: r669887

Rahul Akolkar
On 6/20/08, [hidden email] <[hidden email]> wrote:
> Author: sgoeschl
>  Date: Fri Jun 20 06:21:04 2008
>  New Revision: 669887
>
>  URL: http://svn.apache.org/viewvc?rev=669887&view=rev
>  Log:
>  Added note that those classes are not part of the public API
>
<snip/>

I'm not sure how we'd consider breakage though (does that mean we'll
be lax with changes to these classes?).

I mention this because there are a couple of classes in [scxml] as
well that fit this bill and we could add similar warnings there. But
these warnings clearly have no merit when it comes to clirr or
jardiff, so we must be assuming that everyone reads Javadocs very
carefully ;-)

-Rahul


>  Modified:
>     commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/MapUtils.java
>     commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/StringUtils.java
>
>  Modified: commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/MapUtils.java
>  URL: http://svn.apache.org/viewvc/commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/MapUtils.java?rev=669887&r1=669886&r2=669887&view=diff
>  ==============================================================================
>  --- commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/MapUtils.java (original)
>  +++ commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/MapUtils.java Fri Jun 20 06:21:04 2008
>  @@ -24,7 +24,8 @@
>
>   /**
>   * Helper classes to manipulate maps to pass substition map to the
>  - * CommandLine.
>  + * CommandLine. This class is not part of the public API and
>  + * could change without warning.
>   *
>   * @author <a href="mailto:[hidden email]">Siegfried Goeschl</a>
>   */
>
>  Modified: commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/StringUtils.java
>  URL: http://svn.apache.org/viewvc/commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/StringUtils.java?rev=669887&r1=669886&r2=669887&view=diff
>  ==============================================================================
>  --- commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/StringUtils.java (original)
>  +++ commons/sandbox/exec/trunk/src/main/java/org/apache/commons/exec/util/StringUtils.java Fri Jun 20 06:21:04 2008
>  @@ -26,7 +26,9 @@
>
>   /**
>   * Supplement of commons-lang, the stringSubstitution() was in a simpler
>  - * implementation available in an older commons-lang implementation
>  + * implementation available in an older commons-lang implementation.
>  + * This class is not part of the public API and could change without
>  + * warning.
>   *
>   * @author <a href="mailto:[hidden email]">Siegfried Goeschl</a>
>   */
>
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [all] svn commit: r669887

James Carman
On Fri, Jun 20, 2008 at 4:47 PM, Rahul Akolkar <[hidden email]> wrote:

> On 6/20/08, [hidden email] <[hidden email]> wrote:
>> Author: sgoeschl
>>  Date: Fri Jun 20 06:21:04 2008
>>  New Revision: 669887
>>
>>  URL: http://svn.apache.org/viewvc?rev=669887&view=rev
>>  Log:
>>  Added note that those classes are not part of the public API
>>
> <snip/>
>
> I'm not sure how we'd consider breakage though (does that mean we'll
> be lax with changes to these classes?).
>
> I mention this because there are a couple of classes in [scxml] as
> well that fit this bill and we could add similar warnings there. But
> these warnings clearly have no merit when it comes to clirr or
> jardiff, so we must be assuming that everyone reads Javadocs very
> carefully ;-)

The maven plugin for clirr does have an "excludes" parameter.  We
could come up with a naming convention for non-public classes that we
don't want folks using (someone suggested underscores or something)
and set that up in the parent pom.xml file.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [all] svn commit: r669887

Torsten Curdt
>>> Added note that those classes are not part of the public API
>>>
>> <snip/>
>>
>> I'm not sure how we'd consider breakage though (does that mean we'll
>> be lax with changes to these classes?).
>>
>> I mention this because there are a couple of classes in [scxml] as
>> well that fit this bill and we could add similar warnings there. But
>> these warnings clearly have no merit when it comes to clirr or
>> jardiff, so we must be assuming that everyone reads Javadocs very
>> carefully ;-)
>
> The maven plugin for clirr does have an "excludes" parameter.  We
> could come up with a naming convention for non-public classes that we
> don't want folks using (someone suggested underscores or something)
> and set that up in the parent pom.xml file.

Underscore? *shudder*
What about a package name called "internal"

cheers
--
Torsten

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [all] svn commit: r669887

James Carman
On Sun, Jun 22, 2008 at 9:35 AM, Torsten Curdt <[hidden email]> wrote:

> Underscore? *shudder*
> What about a package name called "internal"

I don't really care what the naming convention is.   I was just making
a suggestion of how we could allow APIs to change as long as they're
marked as internal.  We can come up with the best way to do so based
on everyone's opinion (for the record, I'm not big on underscores
either, but they definitely would draw attention to themselves).

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [all] svn commit: r669887

Rahul Akolkar
In reply to this post by Torsten Curdt
Please stop removing the "headers" from the reply body (for example,
I've retained the "On 6/22/08, Torsten Curdt <[hidden email]>
wrote:" text below). Removing those makes conversations quite hard to
follow, especially the longer ones.

On 6/22/08, Torsten Curdt <[hidden email]> wrote:

> >
> > >
> > > > Added note that those classes are not part of the public API
> > > >
> > > >
> > > <snip/>
> > >
> > > I'm not sure how we'd consider breakage though (does that mean we'll
> > > be lax with changes to these classes?).
> > >
> > > I mention this because there are a couple of classes in [scxml] as
> > > well that fit this bill and we could add similar warnings there. But
> > > these warnings clearly have no merit when it comes to clirr or
> > > jardiff, so we must be assuming that everyone reads Javadocs very
> > > carefully ;-)
> > >
> >
> > The maven plugin for clirr does have an "excludes" parameter.  We
> > could come up with a naming convention for non-public classes that we
> > don't want folks using (someone suggested underscores or something)
> > and set that up in the parent pom.xml file.
> >
>
>  Underscore? *shudder*
>  What about a package name called "internal"
>
<snip/>

Yup, a reserved package name makes sense ("internal" is fine, and
atleast a couple of Apache projects use it). If there aren't any
objections, we should document this and start using the convention.

-Rahul


>
>  cheers
>  --
>  Torsten
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [all] svn commit: r669887

James Carman
On Sun, Jun 22, 2008 at 5:08 PM, Rahul Akolkar <[hidden email]> wrote:
> Yup, a reserved package name makes sense ("internal" is fine, and
> atleast a couple of Apache projects use it). If there aren't any
> objections, we should document this and start using the convention.

I'm really good with whatever everyone else likes.  No real issues
with either way we go on this one.  Just let me know and I'll follow
the guidelines. :)

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

RE: [all] svn commit: r669887

Jörg Schaible-2
[hidden email] wrote:
> On Sun, Jun 22, 2008 at 5:08 PM, Rahul Akolkar
> <[hidden email]> wrote:
>> Yup, a reserved package name makes sense ("internal" is fine, and
>> atleast a couple of Apache projects use it). If there aren't any
>> objections, we should document this and start using the convention.
>
> I'm really good with whatever everyone else likes.  No real issues
> with either way we go on this one.  Just let me know and I'll follow
> the guidelines. :)

Well, at least we may exclude the javadoc of the internal classes. If we find an common pattern we can configure the javadoc plugin in the parent POM.

- Jörg

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]