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
Mark Combellack| Software Developer| Avaya | Eastern Business Park | St. Mellons | Cardiff |
CF3 5EA | Voice: +44 (0) 29 2081 7624 |
> -----Original Message-----
> From: Simon Nash
[mailto:]
> 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
