sdo message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [sdo] ISSUE 164: SDO Compliant Documentation
- From: "Barack, Ron" <ron.barack@sap.com>
- To: "Bryan Aupperle" <aupperle@us.ibm.com>
- Date: Sun, 16 Aug 2009 11:02:56 +0200
Hi Bryan,
Thanks for reviewing the document. I'm not sure how
MAY's can be normative...after all, they are explicitly saying we cannot test
for the behavior. But in any case, all the text having to do with "MAY
throw an exception" is really just a waste of space. I mean, what does it
tell the user when we say that an implementation MAY throw an exception, but, on
the otherhand, it may accept the input?
Another point is that I removed MUSTs from lines like "the
getRootObject method MUST return the root object." I think we need some
kind of text that says the API has to be fully implemented, and the normative
statements in the docu go beyond the behavior described in the javadoc..."
otherwise the spec just becomes too unreadable.
At least, that was my reasoning. I guess this will
all be discussed on Tuesday's meeting. Have fun! I'll be in
Barcelona :-)
Ron
Lines with MAYs that need
review:
There is a set dealing with
throwing exceptions (380, 413, 549, 553, 554, 1013, 1628 and 1648). While
these are OK, there may be a better way to discuss error handling once and not
have all of these individual MAYs.
There is a set dealing with the language specs (244, 245, 263 and 264).
Unless we make language specifications conformance targets (not the SCA
pattern), we need reword these.
711-713 and 1488-1489 should be reworded.
Ones that are not really normative statements: 130, 335,
421 (lower case), 491, 672, 844, 1011, 1161 (lower case), 1567 (lower case),
2114&2115, 2201 (lower case).
2343 has a wording problem
Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software
Solution Architect
Research Triangle Park, NC
+1 919-254-7508
(T/L 444-7508)
Internet Address: aupperle@us.ibm.com
From:
| "Barack, Ron"
<ron.barack@sap.com>
|
To:
| <sdo@lists.oasis-open.org>
|
Date:
| 08/14/2009 09:45 AM
|
Subject:
| [sdo] ISSUE 164: SDO Compliant
Documentation |
Hi Everyone,
As discussed, I've created a JIRA issue to discuss
this:
http://www.osoa.org/jira/browse/SDO-164
As promised, I've uploaded a first pass at the core
spec here: http://www.oasis-open.org/apps/org/workgroup/sdo/download.php/33803/sdo-core-090814.doc
The version has an appendix where the compliance
points are listed, with links to the relevant sections of the spec…I believe
that this is what Brian was referring to when he said we should copy what was
done in the SCA assembly TC.
I've used the keyword MUST to indicate a compliance
point for the implementation. I tried to keep these limited to stuff for
which I could imagine writing a test. For constraints on application, I
used "requires". I noticed that the SCA spec also has compliance points on
things like the SCDL files, so it seemed OK to use 2119 language here. The
appendix contains only MUSTS.
Of course I had to make a bunch of editorial changes,
and as I was going thru I reworked some paragraphs that I thought were unclear.
I tried not to alter the meaning of anything, only to clarify, but this
requires everyone review the changes. The only big change was that I
removed section 4.2.7, on change summary serialization, to chapter 11
(ChangeSummary XML Format).
Best Regards,
Ron
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]