RE: [sca-j] ISSUE 121: Work in progress zip file

Hi Simon,

I have had a quick look over the zip file and have the following comments.

There is no package.html file containing JavaDoc for the org.oasisopen.sca and org.oasisopen.sca.annotation packages
Perhaps we should add a footer to the JavaDoc pages detailing the OASIS copyright information and version. See http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#footer
Oasis copyright ought to have 2009 in the headers too
There are several JavaDoc warnings produced by Eclipse. It may be worth attempting to fix these. I’ve included the Eclipse warnings at the end of this email

Regarding your comment on all interfaces, classes and exception being in one list for all classes. I believe this is the way that it works. If you view an individual package, it splits them up by type. For example, see JDK 1.6 JavaDoc at http://java.sun.com/javase/6/docs/api/index.html. The overall index has them all grouped together but if you view an individual package, it splits them up.

The reason why the ComponentContext does not have any JavaDoc is because it does not have a JavaDoc comment at the start of the class. It just has an ordinary comment. The way to fix this is to change it so that the comment starts with /** rather than /* (i.e. two star characters)

Is it worth storing these in the OASIS Open SVN repository? I believe that it is. The benefits of this include:

Centralised point of storage
Version History
Multiple people can work on them at the same time (there are several really minor editorial issues that I could fix this way)
We can then use Tags to mark a particular version to go along with each revision of the specification

See http://lists.oasis-open.org/archives/sca-j/200901/msg00115.html for more information on the SVN repository.

Thanks,

Mark

Eclipse JavaDoc warning errors:

Description Resource Path Location Type

Javadoc: Missing comment for public declaration Authentication.java java121/src/org/oasisopen/sca/annotation line 27 Java Problem

Javadoc: Missing comment for public declaration Authentication.java java121/src/org/oasisopen/sca/annotation line 28 Java Problem

Javadoc: Missing comment for public declaration Authentication.java java121/src/org/oasisopen/sca/annotation line 29 Java Problem

Javadoc: Missing comment for public declaration ComponentContext.java java121/src/org/oasisopen/sca line 12 Java Problem

Javadoc: Missing comment for public declaration Confidentiality.java java121/src/org/oasisopen/sca/annotation line 27 Java Problem

Javadoc: Missing comment for public declaration Confidentiality.java java121/src/org/oasisopen/sca/annotation line 28 Java Problem

Javadoc: Missing comment for public declaration Confidentiality.java java121/src/org/oasisopen/sca/annotation line 29 Java Problem

Javadoc: Missing comment for public declaration Constants.java java121/src/org/oasisopen/sca line 13 Java Problem

Javadoc: Missing comment for public declaration Constants.java java121/src/org/oasisopen/sca line 15 Java Problem

Javadoc: Missing comment for public declaration Integrity.java java121/src/org/oasisopen/sca/annotation line 28 Java Problem

Javadoc: Missing comment for public declaration Integrity.java java121/src/org/oasisopen/sca/annotation line 29 Java Problem

Javadoc: Missing comment for public declaration Integrity.java java121/src/org/oasisopen/sca/annotation line 30 Java Problem

Javadoc: Missing comment for public declaration Property.java java121/src/org/oasisopen/sca/annotation line 49 Java Problem

Javadoc: Missing comment for public declaration Property.java java121/src/org/oasisopen/sca/annotation line 57 Java Problem

Javadoc: Missing comment for public declaration Reference.java java121/src/org/oasisopen/sca/annotation line 46 Java Problem

Javadoc: Missing comment for public declaration Reference.java java121/src/org/oasisopen/sca/annotation line 55 Java Problem

Javadoc: Missing tag for parameter B ComponentContext.java java121/src/org/oasisopen/sca line 40 Java Problem

Javadoc: Missing tag for parameter B ComponentContext.java java121/src/org/oasisopen/sca line 55 Java Problem

Javadoc: Missing tag for parameter B ComponentContext.java java121/src/org/oasisopen/sca line 68 Java Problem

Javadoc: Missing tag for parameter B ComponentContext.java java121/src/org/oasisopen/sca line 81 Java Problem

Javadoc: Missing tag for parameter B ComponentContext.java java121/src/org/oasisopen/sca line 93 Java Problem

Javadoc: Missing tag for parameter B ComponentContext.java java121/src/org/oasisopen/sca line 106 Java Problem

Javadoc: Missing tag for parameter B ComponentContext.java java121/src/org/oasisopen/sca line 116 Java Problem

Javadoc: Missing tag for parameter B ComponentContext.java java121/src/org/oasisopen/sca line 125 Java Problem

Javadoc: Missing tag for parameter B RequestContext.java java121/src/org/oasisopen/sca line 61 Java Problem

Javadoc: Missing tag for parameter B ServiceReference.java java121/src/org/oasisopen/sca line 12 Java Problem

Javadoc: Missing tag for parameter CB RequestContext.java java121/src/org/oasisopen/sca line 39 Java Problem

Javadoc: Missing tag for parameter CB RequestContext.java java121/src/org/oasisopen/sca line 49 Java Problem

Javadoc: Missing tag for parameter R ComponentContext.java java121/src/org/oasisopen/sca line 125 Java Problem

> -----Original Message-----

> From: Simon Nash [mailto:oasis@cjnash.com]

> Sent: 10 February 2009 23:55

> To: OASIS Java

> Subject: Re: [sca-j] ISSUE 121: Work in progress zip file

> I have uploaded a second draft of the SCA-J APIs and annotations

> zip file here:

> http://www.oasis-open.org/apps/org/workgroup/sca-

> j/download.php/31164/javacaa-code-draft2.zip

> This contains the complete set of APIs and annotations.

> Here are some points for editorial action that I noted while

> going through the annotations.

> 1. Out of order import statements in @AllowsPassByReference,

> @Callback, @ComponentName, @Context, @Property, @Reference.

> 2. Wrong syntax for @Target in @Callback.

> 3. Wrong package name in @Confidentiality.

> 4. Wrong import package name in @Integrity (for Constants import).

> 5. Inconsistencies between @Property and @Reference wording:

> a. First sentence of second paragraph of @Property description

> ("The @Property.....method parameter.") is redundant and

> should be removed. Also remove "However," at start of

> following sentence.

> b. @Reference should say "specifies" at start of description

> of "required" attribute.

> Comments are most welcome.

> Simon

> Simon Nash wrote:

> > I have uploaded a partial first draft of the SCA-J APIs and

> > annotations zip file here:

> > http://www.oasis-open.org/apps/org/workgroup/sca-

> j/download.php/31135/javacaa-code-draft1.zip

> >

> > At present only the contents of the org.oasisopen.sca package are

> > included. I would welcome any comments on how I have done this

> > before I proceed with adding the annotations. In particular:

> >

> > a) I was surprised to see that the javadoc index page puts all

> > interfaces, classes and exceptions together into a single list.

> > Other javadocs I have seen have had separate lists for these.

> > Does anyone know how to get these separated into separate lists?

> >

> > b) I'm surprised to see no description for ComponentContext on

> > the overview page. There is a short description for this in

> > the source file. Does anyone know how to fix this?

> >

> > I resisted the temptation to "improve" the descriptions of the

> > interfaces, classes and methods. I think it is important to keep

> > the spec and code fully in sync, and the best way to ensure this

> > is to make any changes in the spec first.

> >

> > As a general comment, some of the descriptions for interfaces,

> > classes and methods are very brief and should be expanded. I have

> > not made specific mention of these. Reading the javadoc should

> > make it fairly clear where changes are needed. I did find some

> > specific points for action or discussion, which are listed below.

> >

> > 1. The descriptions of ComponentContext.getService() and

> > getServiceReference() talk about throwing an

> > IllegalArgumentException, but this is not shown on the

> > signatures. In contrast, ComponentContext.cast() has

> > IllegalArgumentException on the signature but this is

> > not mentioned in the description. How should we handle

> > this for unchecked exceptions?

> >

> > 2. There is a missing "of" in the description of

> > ComponentContext.getServiceReferences(): "... list typed

> > service references...".

> >

> > 3. On ComponentContext, the method descriptions for

> > getRequestContext() and cast() are in the wrong order.

> >

> > 4. ComponentContext needs an import for java.util.Collection.

> >

> > 5. In the description of RequestContext.getServiceReference(),

> > "CallableReference" needs to be changed to "ServiceReference".

> >

> > More later...

> >

> > Simon

> >

> > ---------------------------------------------------------------------

> > To unsubscribe from this mail list, you must leave the OASIS TC that

> > generates this mail. Follow this link to all your TCs in OASIS at:

> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

> >

> ---------------------------------------------------------------------

> To unsubscribe from this mail list, you must leave the OASIS TC that

> generates this mail. Follow this link to all your TCs in OASIS at:

> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

sca-j message