Quantcast

Policy of API compatibility

classic Classic list List threaded Threaded
19 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Policy of API compatibility

Kazutoshi Satoda
Administrator
Hi all,

In some recent mailing on the list, I found some disagreement about the
policy of API compatibility. Clearly, we need some written agreement on
this issue, to make the next stable release come true.

Please post your opinions, and discuss about them. I want to put the
conclusion as a text in docs like I did for docs/release-procedure.txt.


My opinion is:
I like Subversion's policy. It basically uses the same guideline as APR,
which seems widely adopted on various OSS.
http://subversion.tigris.org/hacking.html#release-numbering
In short,
  - it uses MAJOR.MINOR.PATCH numbering, and
  - API breakages are allowed only at major releases. Thus,
  - All plugins and macros written against a release should work with
    all future releases in the same major release series.

However, the rule about API breakage seems too strong. I think we can
add some exception on this; like "we can make some API breakage in a
minor release, provided all plugins on jEdit plugin central can be
upgraded to fix such breakage."

What do you think?
--
k_satoda

------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensign option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Marcelo Vanzin-2
On Mon, Apr 27, 2009 at 12:42 PM, Kazutoshi Satoda
<[hidden email]> wrote:
> I like Subversion's policy. It basically uses the same guideline as APR,
> which seems widely adopted on various OSS.
> http://subversion.tigris.org/hacking.html#release-numbering
> In short,
>  - it uses MAJOR.MINOR.PATCH numbering, and
>  - API breakages are allowed only at major releases. Thus,

This is similar to any policy that any half-sane project should
follow. :-) The differences with jEdit are mainly:

. it's taking forever for us to reach a "major" release; we keep
relesing unstable releases forever, and, kinda by definition, breaking
the API in unstable releases is OK.

. I don't remember the last time that we've had a patch release for a
stable release.

. The biggest problem is defining *what* is the public API. Just
because a class or method is public, it doesn't mean it should be
considered part of the API. The JDK is full of public classes that you
shouldn't use, for example.

If you really want to start a discussion about API policies, I'd first
spend time defining what the API is. Choose packages that should be
considered "the public API", and only generate javadoc for those
packages; everything else, regardless of whether the code says
"public" or not, it not a public API. Then clean up those packages so
that they only really export a public API, and then this discussion
can happen and actually mean something.

--
Marcelo Vanzin
[hidden email]
"Life's too short to drink cheap beer."

------------------------------------------------------------------------------
Crystal Reports &#45; New Free Runtime and 30 Day Trial
Check out the new simplified licensign option that enables unlimited
royalty&#45;free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Kazutoshi Satoda
Administrator
Marcelo Vanzin wrote:
> . The biggest problem is defining *what* is the public API. Just
> because a class or method is public, it doesn't mean it should be
> considered part of the API. The JDK is full of public classes that you
> shouldn't use, for example.

Thank you for quick suggestion.

I have thought as followings:
  - A package is an API-package if it is not documented as non-API.
    Note that "documented as non-API" means it is documented such as:
      - "This is not a part of API", or
      - "Users shouldn't use this directly", or
      - etc...
  - A class is an API-class if it is declared public in an API-package
    or an API-class, and it is not documented as non-API.
  - A non-class member of a class is an API-member if it is declared
    public in an API-class, and it is not documented as non-API.
  - the public API is consist of API-packages, API-classes in them, and
    API-members in them.

Is there any problem with this?
--
k_satoda

------------------------------------------------------------------------------
Crystal Reports &#45; New Free Runtime and 30 Day Trial
Check out the new simplified licensign option that enables unlimited
royalty&#45;free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Dale Anson
Administrator
Is there such documentation now?  That is, how does anyone know if some plugin is using some code that should properly be marked as non-API?  I would think that for now, any class or method that is currently public should be assumed to be part of the public API.  As such methods are found that should not be part of the public API, perhaps they should be augmented with a private or protected method with the old public method simply calling the new method and marking the old method as deprecated.  Then the old method is elibible for removal at the next major release.

Dale


On Mon, Apr 27, 2009 at 2:22 PM, Kazutoshi Satoda <[hidden email]> wrote:
Marcelo Vanzin wrote:
> . The biggest problem is defining *what* is the public API. Just
> because a class or method is public, it doesn't mean it should be
> considered part of the API. The JDK is full of public classes that you
> shouldn't use, for example.

Thank you for quick suggestion.

I have thought as followings:
 - A package is an API-package if it is not documented as non-API.
   Note that "documented as non-API" means it is documented such as:
     - "This is not a part of API", or
     - "Users shouldn't use this directly", or
     - etc...
 - A class is an API-class if it is declared public in an API-package
   or an API-class, and it is not documented as non-API.
 - A non-class member of a class is an API-member if it is declared
   public in an API-class, and it is not documented as non-API.
 - the public API is consist of API-packages, API-classes in them, and
   API-members in them.

Is there any problem with this?
--
k_satoda

------------------------------------------------------------------------------
Crystal Reports &#45; New Free Runtime and 30 Day Trial
Check out the new simplified licensign option that enables unlimited
royalty&#45;free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel


------------------------------------------------------------------------------
Crystal Reports &#45; New Free Runtime and 30 Day Trial
Check out the new simplified licensign option that enables unlimited
royalty&#45;free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Kazutoshi Satoda
Administrator
Dale Anson wrote:
> Is there such documentation now?

Sorry, I wrote the "documented as non-API" part with my old memory
that I saw such part in jEdit code tree.

Searching for "API" didn't find any part saying like "This is not a
part of API".

Searching for "directly" gave some result which are saying "You should
not use it directly" in jedit.buffer package.

--
k_satoda

------------------------------------------------------------------------------
Crystal Reports &#45; New Free Runtime and 30 Day Trial
Check out the new simplified licensign option that enables unlimited
royalty&#45;free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Alan Ezust-3
Administrator
Yeah, a consistent way of marking non-API classes would be nice. I'm sure that some are marked "not meant for public use" and others are marked "not use directly".

API is indeed the right acronym and should appear in each comment that indicates it is not part of the API, I think to help with consistency and skipping them during the doc generation process.



On Mon, Apr 27, 2009 at 2:12 PM, Kazutoshi Satoda <[hidden email]> wrote:
Dale Anson wrote:
> Is there such documentation now?

Sorry, I wrote the "documented as non-API" part with my old memory
that I saw such part in jEdit code tree.

Searching for "API" didn't find any part saying like "This is not a
part of API".

Searching for "directly" gave some result which are saying "You should
not use it directly" in jedit.buffer package.

--
k_satoda

------------------------------------------------------------------------------
Crystal Reports &#45; New Free Runtime and 30 Day Trial
Check out the new simplified licensign option that enables unlimited
royalty&#45;free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel


------------------------------------------------------------------------------
Crystal Reports &#45; New Free Runtime and 30 Day Trial
Check out the new simplified licensign option that enables unlimited
royalty&#45;free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Kazutoshi Satoda
Administrator
Alan Ezust wrote:
> Yeah, a consistent way of marking non-API classes would be nice. I'm sure
> that some are marked "not meant for public use" and others are marked "not
> use directly".
>
> API is indeed the right acronym and should appear in each comment that
> indicates it is not part of the API, I think to help with consistency and
> skipping them during the doc generation process.

I think "This is not a part of API" is a straightforward wording.
Alan, could you please replace the wording of such public classes?

While I think, as Dale said, it is not to good to distinguish API by
documentation, it looks too hard to restructure the packages so that
all such classes can be declared non-public.

So, assuming we got consistent wordings for non-API, I propose the
following definition for API. Now it has words for protected, too.

  - A package is an API-package if it is not documented as non-API.
    Note that "documented as non-API" means the following sentence is
    included in its javadoc; "This is not a part of API".
  - A class is an API-class if it is declared public in an API-package
    and not documented as non-API, or declared public or protected in
    an API-class.
  - A non-class member of a class is an API-member if it is declared
    public or protected in an API-class.
  - the API is consist of API-packages, API-classes in them, and
    API-members in them.

If no one objects, I want the original discussion about compatibility
starts with this definition of API.
--
k_satoda

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Marcelo Vanzin-2
On Wed, Apr 29, 2009 at 6:24 AM, Kazutoshi Satoda
<[hidden email]> wrote:
> I think "This is not a part of API" is a straightforward wording.
> Alan, could you please replace the wording of such public classes?
>
> While I think, as Dale said, it is not to good to distinguish API by
> documentation, it looks too hard to restructure the packages so that
> all such classes can be declared non-public.

Why not just not include the non-API packages (or classes if you want
to go into that level of granularity) in the "public" javadoc? That
way it's easy: if it's documented in the javadocs provided with jEdit,
you can safely use it.

We can have an ant target to generate all docs (including non-public
APIs) if developers feel they need it.

This is what Sun does, and you don't see people using all the sun.*
classes which are available in the JRE in their programs. If you do,
you're on your own.

This is much easier than refactoring everything so that you have
proper public / protected / private classes, which in some cases is
not even possible unless you want all your code to live in the same
package, which can become a mess very easily.


--
Marcelo Vanzin
[hidden email]
"Life's too short to drink cheap beer."

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Matthieu Casanova
Administrator
But how do you force javadoc to remove the non api methods ? Some of them may be "public" but not part of the api.
Maybe an annotation ?

Matthieu

2009/4/29 Marcelo Vanzin <[hidden email]>
On Wed, Apr 29, 2009 at 6:24 AM, Kazutoshi Satoda
<[hidden email]> wrote:
> I think "This is not a part of API" is a straightforward wording.
> Alan, could you please replace the wording of such public classes?
>
> While I think, as Dale said, it is not to good to distinguish API by
> documentation, it looks too hard to restructure the packages so that
> all such classes can be declared non-public.

Why not just not include the non-API packages (or classes if you want
to go into that level of granularity) in the "public" javadoc? That
way it's easy: if it's documented in the javadocs provided with jEdit,
you can safely use it.

We can have an ant target to generate all docs (including non-public
APIs) if developers feel they need it.

This is what Sun does, and you don't see people using all the sun.*
classes which are available in the JRE in their programs. If you do,
you're on your own.

This is much easier than refactoring everything so that you have
proper public / protected / private classes, which in some cases is
not even possible unless you want all your code to live in the same
package, which can become a mess very easily.


--
Marcelo Vanzin
[hidden email]
"Life's too short to drink cheap beer."

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel


------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Marcelo Vanzin-2
On Wed, Apr 29, 2009 at 3:22 PM, Matthieu Casanova
<[hidden email]> wrote:
> But how do you force javadoc to remove the non api methods ? Some of them
> may be "public" but not part of the api.
> Maybe an annotation ?

I'm assuming that we don't want to get into a situation where the same
class has public methods which are "public API" and public methods
which are not. I think that's bad design.

My suggestion was to control "the public API" by packages; we have
packages which we consider public and generate docs for, and packages
which are not. If that is not deemed enough, we could do it at class
granularity (also equals more maintenance related to the ant task that
generates the docs).

But I really don't like the idea of mixing public and non-public APIs
in the same class.

--
Marcelo Vanzin
[hidden email]
"Life's too short to drink cheap beer."

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Kazutoshi Satoda
Administrator
In reply to this post by Marcelo Vanzin-2
Marcelo Vanzin wrote:

> On Wed, Apr 29, 2009 at 6:24 AM, Kazutoshi Satoda
> <[hidden email]> wrote:
>> I think "This is not a part of API" is a straightforward wording.
>> Alan, could you please replace the wording of such public classes?
>>
>> While I think, as Dale said, it is not to good to distinguish API by
>> documentation, it looks too hard to restructure the packages so that
>> all such classes can be declared non-public.
>
> Why not just not include the non-API packages (or classes if you want
> to go into that level of granularity) in the "public" javadoc? That
> way it's easy: if it's documented in the javadocs provided with jEdit,
> you can safely use it.

+1 for excluding the non-API package or classes in API docs.

However, I want the distinction to be clear and easy to find while
working on the core. Placing the distinction in the comment for such
classes (in *.java file) will be better for that.

I think the consistent wording can be used to automatically exclude such
classes from the resulted API docs. (Excuse me but I'm not sure that it
can be done in an Ant task. I just know it is possible in theory.)

--
k_satoda

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Kazutoshi Satoda
Administrator
In reply to this post by Marcelo Vanzin-2
Marcelo Vanzin wrote:
> On Wed, Apr 29, 2009 at 3:22 PM, Matthieu Casanova
> <[hidden email]> wrote:
>> But how do you force javadoc to remove the non api methods ? Some of them
>> may be "public" but not part of the api.
>> Maybe an annotation ?
>
> I'm assuming that we don't want to get into a situation where the same
> class has public methods which are "public API" and public methods
> which are not. I think that's bad design.

That's right. My last definition already excluded such methods. I think
they can be easily fixed if it is now wrongly declared as public or
protected.

> My suggestion was to control "the public API" by packages; we have
> packages which we consider public and generate docs for, and packages
> which are not. If that is not deemed enough, we could do it at class
> granularity (also equals more maintenance related to the ant task that
> generates the docs).

Unfortunately, we now live in class granularity. In jedit.buffer package,
some public classes are API but some are documented "internal" and
"should not use directly".
http://www.jedit.org/api/org/gjt/sp/jedit/buffer/package-summary.html

--
k_satoda

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Kazutoshi Satoda
Administrator
Hi Matthieu,

Kazutoshi Satoda wrote:
> Unfortunately, we now live in class granularity. In jedit.buffer package,
> some public classes are API but some are documented "internal" and
> "should not use directly".
> http://www.jedit.org/api/org/gjt/sp/jedit/buffer/package-summary.html

Could you please take another look at the "public" declaration of such
classes?

I found that PositionManager and ContentManager doesn't need to be
public (does compile without "public"), but UndoManager needs it only
for Buffer which is in jedit package. It might be solved with
reasonable work.

--
k_satoda

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Matthieu Casanova
Administrator
In reply to this post by Marcelo Vanzin-2
2009/4/30 Marcelo Vanzin <[hidden email]>
On Wed, Apr 29, 2009 at 3:22 PM, Matthieu Casanova
<[hidden email]> wrote:
> But how do you force javadoc to remove the non api methods ? Some of them
> may be "public" but not part of the api.
> Maybe an annotation ?

I'm assuming that we don't want to get into a situation where the same
class has public methods which are "public API" and public methods
which are not. I think that's bad design.

My suggestion was to control "the public API" by packages; we have
packages which we consider public and generate docs for, and packages
which are not. If that is not deemed enough, we could do it at class
granularity (also equals more maintenance related to the ant task that
generates the docs).

But I really don't like the idea of mixing public and non-public APIs
in the same class.

That's right, but not so easy, it would require to move a lot of classes and would be very complicated, and I'm sure we would have unexpected problems. Of course some public modifiers could be changed but it would never be perfect

Matthieu

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Kazutoshi Satoda
Administrator
Matthieu Casanova wrote:
> 2009/4/30 Marcelo Vanzin <[hidden email]>
>> But I really don't like the idea of mixing public and non-public APIs
>> in the same class.
>
> That's right, but not so easy, it would require to move a lot of classes and
> would be very complicated, and I'm sure we would have unexpected problems.
> Of course some public modifiers could be changed but it would never be
> perfect

If you know such a member, which is public (or protected) but not a part
of API in a API-class, could you please show us one (or more) example?

I don't know such one, and can't imagine why fixing it causes hardness
like you said.

--
k_satoda

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Matthieu Casanova
Administrator
2009/4/30 Kazutoshi Satoda <[hidden email]>
Matthieu Casanova wrote:
2009/4/30 Marcelo Vanzin <[hidden email]>
But I really don't like the idea of mixing public and non-public APIs
in the same class.

That's right, but not so easy, it would require to move a lot of classes and
would be very complicated, and I'm sure we would have unexpected problems.
Of course some public modifiers could be changed but it would never be
perfect

If you know such a member, which is public (or protected) but not a part
of API in a API-class, could you please show us one (or more) example?

I don't know such one, and can't imagine why fixing it causes hardness
like you said.


For example
VFSManager.init()
VFSManager.start()

and probably a lot more

Matthieu

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Kazutoshi Satoda
Administrator
Matthieu Casanova wrote:

> 2009/4/30 Kazutoshi Satoda <[hidden email]>
>> If you know such a member, which is public (or protected) but not a part
>> of API in a API-class, could you please show us one (or more) example?
>>
>> I don't know such one, and can't imagine why fixing it causes hardness
>> like you said.
>>
> For example
> VFSManager.init()
> VFSManager.start()
>
> and probably a lot more

Thanks. I found more 4 occurrences by searching "Do not call". I'll take
a look at these to see how hard to fix them.

If you know other methods or words to search, please let us know.

--
k_satoda

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Vampire (jEdit)
In reply to this post by Kazutoshi Satoda


Kazutoshi Satoda schrieb:
Marcelo Vanzin wrote:
  
On Wed, Apr 29, 2009 at 6:24 AM, Kazutoshi Satoda
[hidden email] wrote:
    
I think "This is not a part of API" is a straightforward wording.
Alan, could you please replace the wording of such public classes?

While I think, as Dale said, it is not to good to distinguish API by
documentation, it looks too hard to restructure the packages so that
all such classes can be declared non-public.
      
Why not just not include the non-API packages (or classes if you want
to go into that level of granularity) in the "public" javadoc? That
way it's easy: if it's documented in the javadocs provided with jEdit,
you can safely use it.
    

+1 for excluding the non-API package or classes in API docs.

However, I want the distinction to be clear and easy to find while
working on the core. Placing the distinction in the comment for such
classes (in *.java file) will be better for that.

I think the consistent wording can be used to automatically exclude such
classes from the resulted API docs. (Excuse me but I'm not sure that it
can be done in an Ant task. I just know it is possible in theory.)

  
I don't think so. For filtering it automated with the words, it must be EXACTLY spelled which is from my experience hard to enforce and addtionally you cannot just exclude or delete the already built JavaDoc pages, because e. g. then there would be dead links in the overview pages and indices. If you don't want to provide the docs for the non-API classes, then you have to exclude it from the doc-build-process already.

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Policy of API compatibility

Vadim Voituk-2
Hi All,

I would like to propose 2 alternatives:

1. "Soft" method
I`m agreed with Matthieu about the annotation.
I`ll be better than using "This is not a part of API" string.

2. "Hardcode" method
In the future major release (4.5 ???) we can mark ONLY API method and
classes with annotation (eg. @PublicAPI)
and depending of the plugin needs, continuously mark core methods with
this annotation.

--
Voituk Vadim
[hidden email]
ICQ#944328
Skype: voituk
Sent from Kiev, 30, Ukraine


On Fri, May 1, 2009 at 02:10, Vampire (jEdit) <[hidden email]> wrote:

>
>
> Kazutoshi Satoda schrieb:
>
> Marcelo Vanzin wrote:
>
>
> On Wed, Apr 29, 2009 at 6:24 AM, Kazutoshi Satoda
> <[hidden email]> wrote:
>
>
> I think "This is not a part of API" is a straightforward wording.
> Alan, could you please replace the wording of such public classes?
>
> While I think, as Dale said, it is not to good to distinguish API by
> documentation, it looks too hard to restructure the packages so that
> all such classes can be declared non-public.
>
>
> Why not just not include the non-API packages (or classes if you want
> to go into that level of granularity) in the "public" javadoc? That
> way it's easy: if it's documented in the javadocs provided with jEdit,
> you can safely use it.
>
>
> +1 for excluding the non-API package or classes in API docs.
>
> However, I want the distinction to be clear and easy to find while
> working on the core. Placing the distinction in the comment for such
> classes (in *.java file) will be better for that.
>
> I think the consistent wording can be used to automatically exclude such
> classes from the resulted API docs. (Excuse me but I'm not sure that it
> can be done in an Ant task. I just know it is possible in theory.)
>
>
>
> I don't think so. For filtering it automated with the words, it must be
> EXACTLY spelled which is from my experience hard to enforce and addtionally
> you cannot just exclude or delete the already built JavaDoc pages, because
> e. g. then there would be dead links in the overview pages and indices. If
> you don't want to provide the docs for the non-API classes, then you have to
> exclude it from the doc-build-process already.
>
> ------------------------------------------------------------------------------
> Register Now & Save for Velocity, the Web Performance & Operations
> Conference from O'Reilly Media. Velocity features a full day of
> expert-led, hands-on workshops and two days of sessions from industry
> leaders in dedicated Performance & Operations tracks. Use code vel09scf
> and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
> --
> -----------------------------------------------
> jEdit Developers' List
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/jedit-devel
>
>

------------------------------------------------------------------------------
Register Now & Save for Velocity, the Web Performance & Operations
Conference from O'Reilly Media. Velocity features a full day of
expert-led, hands-on workshops and two days of sessions from industry
leaders in dedicated Performance & Operations tracks. Use code vel09scf
and Save an extra 15% before 5/3. http://p.sf.net/sfu/velocityconf
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Loading...