Re: [eclipse-dev] New API tooling tags

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]

Re: [eclipse-dev] New API tooling tags

From: Kevin McGuire <Kevin_McGuire@xxxxxxxxxx>
Date: Fri, 4 Apr 2008 12:58:58 -0400
Delivered-to: eclipse-dev@xxxxxxxxxxx
List-archive: <https://dev.eclipse.org/mailman/private/eclipse-dev>
List-help: <mailto:eclipse-dev-request@eclipse.org?subject=help>
List-subscribe: <https://dev.eclipse.org/mailman/listinfo/eclipse-dev>, <mailto:eclipse-dev-request@eclipse.org?subject=subscribe>
List-unsubscribe: <https://dev.eclipse.org/mailman/listinfo/eclipse-dev>, <mailto:eclipse-dev-request@eclipse.org?subject=unsubscribe>

A neat idea but I think I'd prefer to be able to read straight off all the relevant info without mousing (also an accessibility concern in there). Plus what happens for printing? etc. Low tech seems to win in this case.

Pascal Rapicault/Ottawa/IBM@IBMCA
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

04/03/2008 05:45 PM

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	Re: [eclipse-dev] New API tooling tags

>tools but aren't a replacement for well thought out text words, imho. Unless there was a way to hover over them and get them to display something meaningful? From: Kevin McGuire/Ottawa/IBM@IBMCA To: "General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx> Date: 04/03/2008 05:05 PM Subject: Re: [eclipse-dev] New API tooling tags Yeah I agree with John. While in general removing redundancy is clearly good, the primary role of the javadoc comments is human documentation and thus it should be easy to digest by the widest audience of programmers (some of whom may not know how to interpret the tags). The tags provide a nice consistency as well as some ability for automated tools but aren't a replacement for well thought out text words, imho. John Arthorne/Ottawa/IBM@IBMCA Sent by: eclipse-dev-bounces@xxxxxxxxxxx To "General development mailing list of the Eclipse project." 04/03/2008 10:13 AM <eclipse-dev@xxxxxxxxxxx> cc Please respond to Subject "General development mailing list Re: [eclipse-dev] New API of the Eclipse project." tooling tags <eclipse-dev@xxxxxxxxxxx> I like having a human-readable text description next to the tag. This may seem redundant if you understand the meaning of these tags, but these are not standard javadoc tags and we can't assume users browsing the source will understand exactly what they mean. Markus Keller <markus_keller@xxxxxxxxxx> Sent by: eclipse-dev-bounces@xxxxxxxxxxx To "General development mailing list of the Eclipse project." 04/03/2008 09:12 AM <eclipse-dev@xxxxxxxxxxx> cc Please respond to Subject "General development mailing list Re: [eclipse-dev] New API of the Eclipse project." tooling tags <eclipse-dev@xxxxxxxxxxx> Redundancy in code is evil. I would only keep the old comments if they add more information than the API tools tags can express. Otherwise, add the API tools tag(s), but *without* additional description. If we fear that the API tools tags are not self-explanatory, we could add some tooling support (e.g. to expand them into the full blurb for Javadoc export and in hovers). Markus Martin Aeschlimann/Zurich/IBM@IBMCH Sent by: eclipse-dev-bounces@xxxxxxxxxxx 2008-04-03 14:53 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 _______________________________________________ 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 _______________________________________________ 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

References:
- Re: [eclipse-dev] New API tooling tags
  - From: Pascal Rapicault

Prev by Date: Re: [eclipse-dev] New API tooling tags
Next by Date: [eclipse-dev] Project meta data is out of date for eclipse
Previous by thread: Re: [eclipse-dev] New API tooling tags
Next by thread: Re: [eclipse-dev] New API tooling tags
Index(es):
- Date
- Thread

Breadcrumbs