Re: SOAP API - Warnings & Errors

olivier Thereaux wrote:
> 
> I guess the API documentation is not clear in this regard. Would you  
> have a suggestion of a better way to put it?
> 

As a developer, I need to be able to anticipate possible responses so I want
to know:

   1. All possible children of warnings and errors
   2. Which children are required and which are optional.
   3. If certain children always go (or leave) together, that pattern is
nice to know too.  (for instance I'm guessing that if there's no 'line'
element, there will also be no 'col' element -- but, see, I don't really
know.
   4. Possible quantities of children (for instance, there will only ever be
one 'line' and one 'col' unlike the fact that there may be multiple 'error'
nodes within the 'errorlist'.  I "think" that there are only one of each
child in an 'error' or a 'warning' so this would be more useful in the table
outlining the whole SOAP Response Format.

As to suggestions for specific improvements, that depends on #3.  If you can
clearly break the rules down in to one or two groups of warning 'modes' then
I would break it down that way for maximum clarity like:

Error Elements - All Error elements contain the following child elements
 * element
 * line
 * col
 * message
 * messageid
 * explanation
 * source

General Warning - This Warning type deals with the document as a whole and
contains the following child elements:
 * message
 * messageid

Specific Warning - This Warning Type Contains the Following Child Elements
 * element
 * line
 * col
 * message
 * messageid
 * explanation
 * source

Rather than the bulleted list, though, I'd probably use tables like
currently used and include the description of the element.

I'd also add a 3rd column for number of occurrences for each child element
(they'd all be 1 here but in the response format table, you'd have things
like 'doctype' and 'errorlist' with a qty=1 but 'error' and 'warning' would
be qty=0..n -- which is helpful to know).

If you want to be more thorough, the range of possible values for each
element would also be useful (m:line, m:col can only be positive integers,
while m:explanation is HTML wrapped in CDATA, and m:doctype -- while it
always occurs, can be empty).

The real question is whether my simple breakdown of 'warnings' is accurate. 
If, instead, you have 100 different permutations of what can go in a warning
or error, it's becomes harder to convey the true possibilities.

Hope that helps.

-Chris
-- 
View this message in context: http://www.nabble.com/SOAP-API---Warnings---Errors-tf4596626.html#a13129183
Sent from the w3.org - www-validator mailing list archive at Nabble.com.

Received on Wednesday, 10 October 2007 04:27:29 UTC