AW: [rap-dev] Documentation

["Frank Appel" <fappel@xxxxxxxxxxxxxx>]

Hi Jochen,

I see your point, but from a developer point of view, which is the first and most important one that a JavaDoc comment addresses (at least in my opinion) it is very confusing seeing references to version numbers that do not exist. In particular if you are not familiar with RCP. So from my point of view we should really follow Ralf's proposal and think about single sourcing issues when the time has come. Different since tags should not be blocking argument.



Ciao
Frank 

-----Ursprüngliche Nachricht-----
Von: rap-dev-bounces@xxxxxxxxxxx [mailto:rap-dev-bounces@xxxxxxxxxxx] Im Auftrag von Jochen Krause
Gesendet: Dienstag, 25. September 2007 18:35
An: RAP project development-related communication
Betreff: RE: [rap-dev] Documentation

Regarding the since tags in JFace / Workbench I would prefer not to touch them. I hope that we can get to a single sourcing of some of the code in the future and having different since tags will hardly be helpful. This is different for RWT because this is really a specific implementation.

Jochen

-----Original Message-----
From: rap-dev-bounces@xxxxxxxxxxx [mailto:rap-dev-bounces@xxxxxxxxxxx]
On Behalf Of Ralf Sternberg
Sent: Tuesday, September 25, 2007 6:06 PM
To: RAP project development-related communication
Subject: Re: [rap-dev] Documentation

Hi,

Benjamin Muskalla schrieb:
> 1) @since tags. At the moment we have about 60 wrong since tags in
RWT. 
> If nobody cares I'll replace them with @since 1.0.
> What should we do with the tags in JFace, Workbench, Databinding, etc.

> Leave them as is or have them in sync with the RAP release? In my eyes

> we should keep them as is to avoid too much confusion.

It think that also for Workbench, JFace etc., RAP devs are more interested in the RAP version in which a certain method was adopted by RAP. If someone wants to know when a certain method appeared in the original JFace, Workbench, etc. code, he would look it up in the original sources.

To prevent confusion, I'd even prefer "@since RAP1.0" tags. According to the Javadoc style guide [1], we were not the first who used this
notation:

   The convention once was "@since JDK1.2" but because this is a
   specification of the Java Platform, not particular to the Sun JDK or
   SDK, we have dropped "JDK".

BTW, this document also recommends the practice suggested by Benny the other day:

   When a class (or interface) is introduced, specify one @since tag in
   its class description and no @since tags in the members. Add an @since
   tag only to members added in a later version than the class. This
   minimizes the number of @since tags.

[1] http://java.sun.com/j2se/javadoc/writingdoccomments/

Ralf
_______________________________________________
rap-dev mailing list
rap-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/rap-dev
_______________________________________________
rap-dev mailing list
rap-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/rap-dev