[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-j] ISSUE 121: Work in progress zip file
Mark,
Thanks very much for these comments. Responses inline.
Simon
Mark Combellack wrote:
> 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
>
I added these with temporary minimal contents. We need spec words
describing the packages that we can copy to these files.
> * 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
>
Done.
> * Oasis copyright ought to have 2009 in the headers too
>
Done.
> * 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
>
Done, except for those that need spec words to be added.
>
>
>
>
> 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.
>
Now that there are two packages, it looks OK.
>
>
> 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)
>
Done.
>
>
>
>
> 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)
>
I think it's really important to do all such changes in sync
with the spec and these files. This is why I left them a bit
rough in places, to remind us that the spec needs fixing too.
> * 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.
>
I agree with keeping them there. I'd like to wait until JAVA-121 is
resolved with a first draft of these files, and then populate svn
with these files so that the editors can maintain them as needed.
Simon
>
>
> 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 |
> mcombellack@avaya.com <mailto:|mcombellack@avaya.com>
>
>> -----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
>
>
>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]