Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
RE: [eclipse-dev] New API tooling tags

IMO this should be done on a case by case basis.  For example the comments cited below are more information than API definition.  In the first case, the API statement is that the class should not be extended.  Certain friends can extend it but, that feels more like something the consumer would say (i.e., yeah, I know it is not API but its ok, we are collaborating). 

 

In the second example the class can be extended (that’s the API statement).  The comment just tells us who might want to be an extender.

 

Summary is that the comments are just comments/information.  If the developers feel it is interesting information to convey great.

 

Jeff

 

From: eclipse-dev-bounces@xxxxxxxxxxx [mailto:eclipse-dev-bounces@xxxxxxxxxxx] On Behalf Of Philippe P Mulet
Sent: Thursday, April 03, 2008 11:02 AM
To: General development mailing list of the Eclipse project.
Subject: Re: [eclipse-dev] New API tooling tags

 


+1




Martin Aeschlimann <martin_aeschlimann@xxxxxxxxxx>
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

04/03/2008 02:51 PM

Please respond to
"General development mailing list of the Eclipse project."        <eclipse-dev@xxxxxxxxxxx>

To

eclipse-dev@xxxxxxxxxxx

cc

Subject

Re: [eclipse-dev] New API tooling tags

 




We would rather keep the old comments. First it's a lot of work to do it.
Second, most comment contain extra information which sometimes can't be
expressed by the new tags.

* <p>
* Note: this: class is not intended to be extended outside of the
refactoring framework.
* </p>

* <p>>
* This class should be subclassed by clients wishing to provide a special
move
* processor.
* </p>

Thoughts?.

Martin




                                                                                                                               
 From:       Olivier Thomann <Olivier_Thomann@xxxxxxxxxx>                                                                      
                                                                                                                               
 To:         "General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>                              
                                                                                                                               
 Date:       03.04.2008 14:36                                                                                                  
                                                                                                                               
 Subject:    Re: [eclipse-dev] New API tooling tags                                                                            
                                                                                                                               





API Tools doesn't remove the existing description in the javadoc.
It only adds a @noimplement followed by the description based on the
component.xml contents and this should replace the old one. So the user
should remove the old one and keep only the new javadoc tags.
Since the wording of the old description is not consistent among bundles,
we could not simply remove the old one.

API Tools also doesn't add @noinstantiate for abstract classes and doesn't
add @noextend for final classes.

Hope this clarify what API Tools is doing.

Olivier




Szymon Brandys <Szymon.Brandys@xxxxxxxxxx>
Sent by: eclipse-dev-bounces@xxxxxxxxxxx
2008-04-03 06:33
Please respond to
"General development mailing list of the Eclipse project."
<eclipse-dev@xxxxxxxxxxx>


To
"General development mailing list of the Eclipse project."
<eclipse-dev@xxxxxxxxxxx>
cc

Subject
[eclipse-dev] New API tooling tags






I noticed that some redundant entries are created in javadocs,
when a project is converted to use API tooling.

For instance for an interface that is not intended to be implemented, I
will have the old entry "This interface is not intended to be implemented
by clients."
amd the new "@noimplement This interface is not intended to be implemented
by clients.".

I would move the comment to the tag. But maybe there are some tools that
can ignore new tags and users would not see it.
Of course we could just add a tag with no comment and leave the old entry
in javadoc.

Any thoughts?
--
Szymon Brandys

_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev


_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev


_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev



Sauf indication contraire ci-dessus:/ Unless stated otherwise above:
Compagnie IBM France
Siège Social : Tour Descartes, 2, avenue Gambetta, La Défense 5, 92400 Courbevoie
RCS Nanterre 552 118 465
Forme Sociale : S.A.S.
Capital Social : 542.737.118 €
SIREN/SIRET : 552 118 465 02430


Back to the top