Home » General (non-technical) » Eclipse Foundation » API?
| API? [message #19713] |
Tue, 03 May 2005 23:23  |
Eclipse User |
|
|
|
Originally posted by: bob.objfac.com
Following is copied from my posting on the platform-core-dev list, on
one of my least-favorite subjects...
----------------------------------
It's not really obvious what makes sense about it. Any plugin that is
essentially a library plugin with no dependencies on Eclipse might break
with this change. What benefit makes this risk worthwhile?
It gets back to, what does "API" mean in Eclipse? In the rest of the
world, an API is a contract, which usually means something written down.
But so little is written down about the Eclipse contract, e.g.,
virtually nothing about plugin class loading except an obsolete article,
that developers are forced to rely on implied contracts - such as, a
plugin classloader will have access to anything the boot classloader
does. Sadly, it seems rare that such an implied contract is honored by a
committer. This situation seems to encourage poor documentation; to
preserve maximum flexibility, a developer is best off saying nothing at
all. Then, when they pull the rug out from under some developer who was
forced to read the code even to find out what the heck some API does
(the Search API leaps to mind) they can claim "not API". What API?
Bob Foster
Philippe Ombredanne wrote:
> Non re-exporting all makes sense.
> It would be interesting to see/know how many external (non eclipse
> provided plug-ins) it will break.
>
> --
> Cheers
> Philippe
>
> philippe ombredanne | nexB - Open by Design (tm)
> 1 650 799 0949 | pombredanne at nexb.com
> http://www.nexb.com
> -----Original Message-----
> From: platform-core-dev-bounces@eclipse.org
> [mailto:platform-core-dev-bounces@eclipse.org] On Behalf Of Thomas
> Watson
> Sent: Tuesday, May 03, 2005 1:02 PM
> To: platform-core-dev@eclipse.org
> Subject: [platform-core-dev] Bundles which do not require
> org.eclipse.osgi
>
>
>
> In this week I-Build the OSGi framework no longer gives access to
> non-java.* packages provided by the JVM for free. Previously we used to
> always delegate to the boot classloader before delegating to OSGi for
> all class loads. This means non-java.* packages (i.e. java.xml.parsers)
> are not accessible unless the bundle imports the package (using
> Import-Package: java.xml.parsers) or requires the system.bundle (using
> Require-Bundle: org.eclipse.osgi). Most bundles in eclipse require
> org.eclipse.osgi indirectly because they require
> org.eclipse.core.runtime which reexports org.eclipse.osgi. This means
> most bundles in eclipse do get access to the packages provided by the
> JVM profile. The following bundles do not require org.eclipse.osgi
> directly or indirectly.
>
> org.apache.ant
> org.apache.lucene
> org.eclipse.core.boot
> org.eclipse.jdt
> org.eclipse.jdt.doc.isv
> org.eclipse.jdt.doc.user
> org.eclipse.jdt.junit.runtime
> org.eclipse.jdt.source
> org.eclipse.pde.doc.user
> org.eclipse.pde.source
> org.eclipse.platform
> org.eclipse.platform.doc.isv
> org.eclipse.platform.doc.user
> org.eclipse.platform.source
> org.eclipse.sdk
> org.eclipse.swt
> org.eclipse.text
> org.junit
>
> I suspect the following bundles should require the org.eclipse.osgi
> bundle incase they access any non-java.* packages from the JVM:
>
> org.apache.ant
> org.apache.lucene
> org.eclipse.swt
> org.eclipse.text
> org.junit
>
> The rest of the bundles which do not require org.eclipse.osgi do not
> have any actual code in them so there is no need to require anything. I
> want to get confirmation from the core team that we think this is
> necessary before I post to the general eclispe dev mailing list
> requesting these bundles update their manifests to Require-Bundle:
> org.eclipse.osgi.
>
> Thomas Watson
>
> _______________________________________________
> platform-core-dev mailing list
> platform-core-dev@eclipse.org
> https://dev.eclipse.org/mailman/listinfo/platform-core-dev
>
>
|
|
|
| Re: API? [message #19767 is a reply to message #19713] |
Wed, 04 May 2005 19:01  |
| Eclipse User |
|
|
|
Originally posted by: john.eclipsefaq.org
This thread was based on a misunderstanding (or miscommunication) of
some changes in OSGi. These changes will not affect existing plugins in
any way; the plugins listed below are affected because they have
explicitly declared that they opted in to the new version. A more
detailed explanation of the changes will be sent out soon, and the
necessary documentation will be written. Having said that, I agree that
"API" in Eclipse could use a more formal definition. If nothing else, a
consistent understanding of the definition of API is needed across the
many projects starting out at Eclipse.
--
Bob Foster wrote:
> Following is copied from my posting on the platform-core-dev list, on
> one of my least-favorite subjects...
> ----------------------------------
>
> It's not really obvious what makes sense about it. Any plugin that is
> essentially a library plugin with no dependencies on Eclipse might break
> with this change. What benefit makes this risk worthwhile?
>
> It gets back to, what does "API" mean in Eclipse? In the rest of the
> world, an API is a contract, which usually means something written down.
> But so little is written down about the Eclipse contract, e.g.,
> virtually nothing about plugin class loading except an obsolete article,
> that developers are forced to rely on implied contracts - such as, a
> plugin classloader will have access to anything the boot classloader
> does. Sadly, it seems rare that such an implied contract is honored by a
> committer. This situation seems to encourage poor documentation; to
> preserve maximum flexibility, a developer is best off saying nothing at
> all. Then, when they pull the rug out from under some developer who was
> forced to read the code even to find out what the heck some API does
> (the Search API leaps to mind) they can claim "not API". What API?
>
> Bob Foster
>
> Philippe Ombredanne wrote:
> > Non re-exporting all makes sense.
> > It would be interesting to see/know how many external (non eclipse
> > provided plug-ins) it will break.
> >
> > --
> > Cheers
> > Philippe
> >
> > philippe ombredanne | nexB - Open by Design (tm)
> > 1 650 799 0949 | pombredanne at nexb.com
> > http://www.nexb.com
> > -----Original Message-----
> > From: platform-core-dev-bounces@eclipse.org
> > [mailto:platform-core-dev-bounces@eclipse.org] On Behalf Of Thomas
> > Watson
> > Sent: Tuesday, May 03, 2005 1:02 PM
> > To: platform-core-dev@eclipse.org
> > Subject: [platform-core-dev] Bundles which do not require
> > org.eclipse.osgi
> >
> >
> >
> > In this week I-Build the OSGi framework no longer gives access to
> > non-java.* packages provided by the JVM for free. Previously we used to
> > always delegate to the boot classloader before delegating to OSGi for
> > all class loads. This means non-java.* packages (i.e. java.xml.parsers)
> > are not accessible unless the bundle imports the package (using
> > Import-Package: java.xml.parsers) or requires the system.bundle (using
> > Require-Bundle: org.eclipse.osgi). Most bundles in eclipse require
> > org.eclipse.osgi indirectly because they require
> > org.eclipse.core.runtime which reexports org.eclipse.osgi. This means
> > most bundles in eclipse do get access to the packages provided by the
> > JVM profile. The following bundles do not require org.eclipse.osgi
> > directly or indirectly.
> >
> > org.apache.ant
> > org.apache.lucene
> > org.eclipse.core.boot
> > org.eclipse.jdt
> > org.eclipse.jdt.doc.isv
> > org.eclipse.jdt.doc.user
> > org.eclipse.jdt.junit.runtime
> > org.eclipse.jdt.source
> > org.eclipse.pde.doc.user
> > org.eclipse.pde.source
> > org.eclipse.platform
> > org.eclipse.platform.doc.isv
> > org.eclipse.platform.doc.user
> > org.eclipse.platform.source
> > org.eclipse.sdk
> > org.eclipse.swt
> > org.eclipse.text
> > org.junit
> >
> > I suspect the following bundles should require the org.eclipse.osgi
> > bundle incase they access any non-java.* packages from the JVM:
> >
> > org.apache.ant
> > org.apache.lucene
> > org.eclipse.swt
> > org.eclipse.text
> > org.junit
> >
> > The rest of the bundles which do not require org.eclipse.osgi do not
> > have any actual code in them so there is no need to require anything. I
> > want to get confirmation from the core team that we think this is
> > necessary before I post to the general eclispe dev mailing list
> > requesting these bundles update their manifests to Require-Bundle:
> > org.eclipse.osgi.
> >
> > Thomas Watson
> >
> > _______________________________________________
> > platform-core-dev mailing list
> > platform-core-dev@eclipse.org
> > https://dev.eclipse.org/mailman/listinfo/platform-core-dev
> >
> >
|
|
|
| Re: API? [message #19808 is a reply to message #19713] |
Wed, 04 May 2005 20:40 |
| Eclipse User |
|
|
|
Originally posted by: jeff_nospam_mcaffer.ca.ibm.com
Some clarification...
This is absolutely NOT a backward compatibility issue. ALL "old" plugins
continue to run fine and are NOT affected by this change. An "old" plugin is
one that either does not have a manifest.mf or does not have
"Bundle-ManifestVersion: 2" in its manifest.
This issue affects only bundles that have moved to the new syntax and
semantics of Bundle-ManifestVersion: 2. For perspective, the earliest that
anyone would have become a "new" plugin is about M5. Eclipse proper only
picked this up only as people were massaging their plugins (JARing and
updating manifests) in the last month or so. The summary is that this issue
is very localized.
Having said that, we are reviewing how Eclipse can take advantage of the
OSGi R4 spec opportunities for greater portability and performance while
providing the best possible developer experience.
Jeff
"Bob Foster" <bob@objfac.com> wrote in message
news:d591f8$fs1$1@news.eclipse.org...
> Following is copied from my posting on the platform-core-dev list, on
> one of my least-favorite subjects...
> ----------------------------------
>
> It's not really obvious what makes sense about it. Any plugin that is
> essentially a library plugin with no dependencies on Eclipse might break
> with this change. What benefit makes this risk worthwhile?
>
> It gets back to, what does "API" mean in Eclipse? In the rest of the
> world, an API is a contract, which usually means something written down.
> But so little is written down about the Eclipse contract, e.g.,
> virtually nothing about plugin class loading except an obsolete article,
> that developers are forced to rely on implied contracts - such as, a
> plugin classloader will have access to anything the boot classloader
> does. Sadly, it seems rare that such an implied contract is honored by a
> committer. This situation seems to encourage poor documentation; to
> preserve maximum flexibility, a developer is best off saying nothing at
> all. Then, when they pull the rug out from under some developer who was
> forced to read the code even to find out what the heck some API does
> (the Search API leaps to mind) they can claim "not API". What API?
>
> Bob Foster
>
> Philippe Ombredanne wrote:
> > Non re-exporting all makes sense.
> > It would be interesting to see/know how many external (non eclipse
> > provided plug-ins) it will break.
> >
> > --
> > Cheers
> > Philippe
> >
> > philippe ombredanne | nexB - Open by Design (tm)
> > 1 650 799 0949 | pombredanne at nexb.com
> > http://www.nexb.com
> > -----Original Message-----
> > From: platform-core-dev-bounces@eclipse.org
> > [mailto:platform-core-dev-bounces@eclipse.org] On Behalf Of Thomas
> > Watson
> > Sent: Tuesday, May 03, 2005 1:02 PM
> > To: platform-core-dev@eclipse.org
> > Subject: [platform-core-dev] Bundles which do not require
> > org.eclipse.osgi
> >
> >
> >
> > In this week I-Build the OSGi framework no longer gives access to
> > non-java.* packages provided by the JVM for free. Previously we used
to
> > always delegate to the boot classloader before delegating to OSGi for
> > all class loads. This means non-java.* packages (i.e.
java.xml.parsers)
> > are not accessible unless the bundle imports the package (using
> > Import-Package: java.xml.parsers) or requires the system.bundle (using
> > Require-Bundle: org.eclipse.osgi). Most bundles in eclipse require
> > org.eclipse.osgi indirectly because they require
> > org.eclipse.core.runtime which reexports org.eclipse.osgi. This means
> > most bundles in eclipse do get access to the packages provided by the
> > JVM profile. The following bundles do not require org.eclipse.osgi
> > directly or indirectly.
> >
> > org.apache.ant
> > org.apache.lucene
> > org.eclipse.core.boot
> > org.eclipse.jdt
> > org.eclipse.jdt.doc.isv
> > org.eclipse.jdt.doc.user
> > org.eclipse.jdt.junit.runtime
> > org.eclipse.jdt.source
> > org.eclipse.pde.doc.user
> > org.eclipse.pde.source
> > org.eclipse.platform
> > org.eclipse.platform.doc.isv
> > org.eclipse.platform.doc.user
> > org.eclipse.platform.source
> > org.eclipse.sdk
> > org.eclipse.swt
> > org.eclipse.text
> > org.junit
> >
> > I suspect the following bundles should require the org.eclipse.osgi
> > bundle incase they access any non-java.* packages from the JVM:
> >
> > org.apache.ant
> > org.apache.lucene
> > org.eclipse.swt
> > org.eclipse.text
> > org.junit
> >
> > The rest of the bundles which do not require org.eclipse.osgi do not
> > have any actual code in them so there is no need to require anything.
I
> > want to get confirmation from the core team that we think this is
> > necessary before I post to the general eclispe dev mailing list
> > requesting these bundles update their manifests to Require-Bundle:
> > org.eclipse.osgi.
> >
> > Thomas Watson
> >
> > _______________________________________________
> > platform-core-dev mailing list
> > platform-core-dev@eclipse.org
> > https://dev.eclipse.org/mailman/listinfo/platform-core-dev
> >
> >
|
|
|
| Re: API? [message #19854 is a reply to message #19767] |
Thu, 05 May 2005 17:55 |
| Eclipse User |
|
|
|
Originally posted by: bob.objfac.com
> This thread was based on a misunderstanding (or miscommunication)
It seems to have been a bit of both, plus I overreacted based on that
misunderstanding. I screwed up and I apologize to everybody involved.
After I read your response, I went back and re-read Jim des Rivières'
"How to Use the Eclipse API" article. I read it very intently when I
started developing a plug-in for Eclipse in November, 2001, and have
rather scrupulously tried to observe its terms, so this time I read it
asking myself the question, so how come my plug-ins keep breaking?
Virtually every line evoked some painful memory, to the extent that I
resolved to try to respond without any specific examples at all. I have
them in reserve if anyone's interested.
In writing these notes I found myself repeating the word "essential", so
I may as well say what I mean by it up front. "Essential" information is
knowledge without which a plug-in developer cannot succeed.
1. Jim's article gives advice to two different audiences. As a general
comment, it seems heavy on guidance for API users and light on guidance
for API writers. There ought to be about as much advice about what one
should document as about what one should not assume. Perhaps if the
article were organized so that advice to users and writers was given
separately, such issues would be easier to spot.
2. If I were a new contributor to Eclipse and I wanted to improve some
aspect, I would ask myself, what can I change? So I would read Jim's
article at least as far as this sentence: "So if you cannot find the
documentation for something, that's usually a good indicator that it's
not API." And I would think, reasonably enough, if nothing is written
down on this subject, I can change anything I want. Such a rule is
asking for trouble. It's a case of good advice for API users and poor
advice for API writers. I don't know the precise form of the latter, but
surely it should include something like "Consider the current users of
this API. Is this change likely to break any of them? Is there a way to
do this that won't break anybody?"
3. The API article is silent on the subject of plug-in manifests. I'm
pretty sure this is essential information. Is it API?
4. What documentation is part of the API? The javadoc, yes. What about
Help documentation? Are Eclipse-published articles part of the API? If
the answers for the latter are no, then one must ask, is there any
information there that is essential and does not appear in the javadoc?
There's quite a lot. The help and a few of the articles are often the
only places where extension points and interfaces that use or implement
extensions are described together. Why were the articles necessary if
not because a plug-in writer could not be expected to get the job done
with only the bare interfaces and javadoc as a guide?
5. Jim's article provides guidance about the use of null, yet it's such
a continual source of misunderstandings it's worth diving down a level
to look at it. Many contributors think it's a rule that no argument may
be null unless the javadoc says null is allowed, but often it isn't
documented when null is allowed. The rule should be written down
explicitly, especially as guidance for contributors! If you allow null
put it in the javadoc. The article has a very clear rule on returning
null that, unfortunately, is rarely observed in practice. Often whether
or not a method returns null depends on when it is called, e.g., during
initialization. For this reason, there is quite a lot of code in Eclipse
that tests for these undocumented nulls and, usually, does nothing when
they occur. Code smells aside, defensive programming does not help a
plugin developer who needs to know when the return value will not be
null. "May be null if called before/during/after X," would be quite useful.
6. It is rare that the order in which interface methods are called or
may be called appears in the javadoc. One often needs to know this. For
example, when there is a choice between two kinds of listeners triggered
by the same event, which is called first? What are the preconditions
when a listener is called? Sometimes they depend on the undocumented
order in which listeners are added, making the API inherently fragile.
7. The rather stern admonitions in Jim's article are in sharp contrast
to the "monkey see, monkey do" advice given by Gamma and Beck. The
latter explicitly assume that the documentation in a project like
Eclipse will never be quite what it should be so if you want to know how
to do something, go look and see how somebody else does it. Good advice,
except if you do this you will incorporate the assumptions of the
non-API example. There is a culture clash here that I admit I'm not
smart enough to resolve, but there needs to be a better balance than "do
this if you want to get anything done," followed by "shouldn't have done
that!"
Bob Foster
John Arthorne wrote:
> This thread was based on a misunderstanding (or miscommunication) of
> some changes in OSGi. These changes will not affect existing plugins in
> any way; the plugins listed below are affected because they have
> explicitly declared that they opted in to the new version. A more
> detailed explanation of the changes will be sent out soon, and the
> necessary documentation will be written. Having said that, I agree that
> "API" in Eclipse could use a more formal definition. If nothing else, a
> consistent understanding of the definition of API is needed across the
> many projects starting out at Eclipse.
> --
>
> Bob Foster wrote:
>
>> Following is copied from my posting on the platform-core-dev list, on
>> one of my least-favorite subjects...
>> ----------------------------------
>>
>> It's not really obvious what makes sense about it. Any plugin that is
>> essentially a library plugin with no dependencies on Eclipse might
>> break with this change. What benefit makes this risk worthwhile?
>>
>> It gets back to, what does "API" mean in Eclipse? In the rest of the
>> world, an API is a contract, which usually means something written
>> down. But so little is written down about the Eclipse contract, e.g.,
>> virtually nothing about plugin class loading except an obsolete
>> article, that developers are forced to rely on implied contracts -
>> such as, a plugin classloader will have access to anything the boot
>> classloader does. Sadly, it seems rare that such an implied contract
>> is honored by a committer. This situation seems to encourage poor
>> documentation; to preserve maximum flexibility, a developer is best
>> off saying nothing at all. Then, when they pull the rug out from under
>> some developer who was forced to read the code even to find out what
>> the heck some API does (the Search API leaps to mind) they can claim
>> "not API". What API?
>>
>> Bob Foster
>>
>> Philippe Ombredanne wrote:
>> > Non re-exporting all makes sense.
>> > It would be interesting to see/know how many external (non eclipse
>> > provided plug-ins) it will break.
>> >
>> > --
>> > Cheers
>> > Philippe
>> >
>> > philippe ombredanne | nexB - Open by Design (tm)
>> > 1 650 799 0949 | pombredanne at nexb.com
>> > http://www.nexb.com
>> > -----Original Message-----
>> > From: platform-core-dev-bounces@eclipse.org
>> > [mailto:platform-core-dev-bounces@eclipse.org] On Behalf Of Thomas
>> > Watson
>> > Sent: Tuesday, May 03, 2005 1:02 PM
>> > To: platform-core-dev@eclipse.org
>> > Subject: [platform-core-dev] Bundles which do not require
>> > org.eclipse.osgi
>> >
>> >
>> >
>> > In this week I-Build the OSGi framework no longer gives access to
>> > non-java.* packages provided by the JVM for free. Previously we
>> used to
>> > always delegate to the boot classloader before delegating to OSGi for
>> > all class loads. This means non-java.* packages (i.e.
>> java.xml.parsers)
>> > are not accessible unless the bundle imports the package (using
>> > Import-Package: java.xml.parsers) or requires the system.bundle (using
>> > Require-Bundle: org.eclipse.osgi). Most bundles in eclipse require
>> > org.eclipse.osgi indirectly because they require
>> > org.eclipse.core.runtime which reexports org.eclipse.osgi. This means
>> > most bundles in eclipse do get access to the packages provided by the
>> > JVM profile. The following bundles do not require org.eclipse.osgi
>> > directly or indirectly.
>> >
>> > org.apache.ant
>> > org.apache.lucene
>> > org.eclipse.core.boot
>> > org.eclipse.jdt
>> > org.eclipse.jdt.doc.isv
>> > org.eclipse.jdt.doc.user
>> > org.eclipse.jdt.junit.runtime
>> > org.eclipse.jdt.source
>> > org.eclipse.pde.doc.user
>> > org.eclipse.pde.source
>> > org.eclipse.platform
>> > org.eclipse.platform.doc.isv
>> > org.eclipse.platform.doc.user
>> > org.eclipse.platform.source
>> > org.eclipse.sdk
>> > org.eclipse.swt
>> > org.eclipse.text
>> > org.junit
>> >
>> > I suspect the following bundles should require the org.eclipse.osgi
>> > bundle incase they access any non-java.* packages from the JVM:
>> >
>> > org.apache.ant
>> > org.apache.lucene
>> > org.eclipse.swt
>> > org.eclipse.text
>> > org.junit
>> >
>> > The rest of the bundles which do not require org.eclipse.osgi do not
>> > have any actual code in them so there is no need to require
>> anything. I
>> > want to get confirmation from the core team that we think this is
>> > necessary before I post to the general eclispe dev mailing list
>> > requesting these bundles update their manifests to Require-Bundle:
>> > org.eclipse.osgi.
>> >
>> > Thomas Watson
>> >
>> > _______________________________________________
>> > platform-core-dev mailing list
>> > platform-core-dev@eclipse.org
>> > https://dev.eclipse.org/mailman/listinfo/platform-core-dev
>> >
>> >
|
|
|
| Re: API? [message #19976 is a reply to message #19854] |
Fri, 06 May 2005 21:24 |
| Eclipse User |
|
|
|
Originally posted by: john.eclipsefaq.org
I've taken a stab at answering some questions below. My comments, of
course, are not API (IANAAPI).
--
Bob Foster wrote:
> 2. If I were a new contributor to Eclipse and I wanted to improve some
> aspect, I would ask myself, what can I change? So I would read Jim's
> article at least as far as this sentence: "So if you cannot find the
> documentation for something, that's usually a good indicator that it's
> not API." And I would think, reasonably enough, if nothing is written
> down on this subject, I can change anything I want. Such a rule is
> asking for trouble. It's a case of good advice for API users and poor
> advice for API writers. I don't know the precise form of the latter, but
> surely it should include something like "Consider the current users of
> this API. Is this change likely to break any of them? Is there a way to
> do this that won't break anybody?"
Since API is a long term promise, it tends to err on the side of under
specification. To declare something in API implies a long term
commitment to maintaining it in the implementation, and to providing
possibly indefinite backwards-compatibility support for that behaviour.
With a user's hat on, we'd all like API to be laid out in excruciating
detail, but a system with such an API could likely never evolve. The
balancing act of the API writer is to provide enough detail that the
client can use them (the "essential" information as you put it), without
committing to implementation details that may need to change in the
future. However, when it comes to changing a system, I agree that you
need to err on the side of not impacting clients. The questions you ask
about avoiding breaking current users of the API, and whether a change
can be made with less impact, are spot on. The challenge for a
"platform" such as Eclipse is that the set of potential clients is
open-ended, and we have limited means of determining if or how a change
we make will impact potentially unknown existing clients. We continually
engage in thought exercises to try to imagine how a given change might
affect a theoretical client, and we often fail at predicting what real
clients are doing with our APIs.
>
> 3. The API article is silent on the subject of plug-in manifests. I'm
> pretty sure this is essential information. Is it API?
The article only deals with Java artifacts, so it certainly has some
holes. Yes, the manifest format is API. Extension point schemas have
always been treated as API, expect for a small set that are explicitly
documented as for internal use only. Backwards-compatibility support
has always been provided when extension points change.
>
> 4. What documentation is part of the API? The javadoc, yes. What about
> Help documentation? Are Eclipse-published articles part of the API? If
> the answers for the latter are no, then one must ask, is there any
> information there that is essential and does not appear in the javadoc?
> There's quite a lot. The help and a few of the articles are often the
> only places where extension points and interfaces that use or implement
> extensions are described together. Why were the articles necessary if
> not because a plug-in writer could not be expected to get the job done
> with only the bare interfaces and javadoc as a guide?
Help and articles are not API. They aren't typically written with the
same rigour as APIs, with consideration of long-term support, backwards
compatibility, etc. Documentation and articles often describe
implementation details that change from release to release. The doc is
revised and sometimes significantly rewritten between releases, and the
same is true for many articles. The best guarantee one could make is
that doc and articles state what is true about a specific release of
Eclipse. If you are building against that exact release, the
information can be relied upon. They do not promise to be applicable to
all future releases.
Having said that, much documentation does talk about behaviour that is
API. They are often just an easier to read narrative form that ties
together API information from various classes and extension points in
one place. You could compare them to a magazine article that describes
a piece of legislation - they are describing the law, but do not carry
the weight of the actual legal texts. In short, plug-in writers should
use these resources, but consult the API proper when in doubt about what
exactly they can rely on across releases.
> The article has a very clear rule on returning
> null that, unfortunately, is rarely observed in practice.
I realize this is just one detail of the (lack of) API that you find
frustrating, but I'll take this as an opportunity to encourage everyone
to enter bug reports against API. If the API rule are not followed,
it's a bug that needs fixing.
Similarly, if you believe an API does not have all the "essential"
information that is needed to make reasonable use of it, you should
enter a bug to request clarification. A quick search found lots of bugs
that were entirely about API clarification. I picked a couple at random
to link here as examples:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=31174
https://bugs.eclipse.org/bugs/show_bug.cgi?id=37838
If the API does not have all the information you need, then the API is
not doing its job.
--
|
|
|
Goto Forum:
Current Time: Thu Apr 25 09:53:24 GMT 2024
Powered by FUDForum. Page generated in 0.03977 seconds |
] 
Search
Help
Register
Login
Home
