diagnosticMessage (was Re: protocol-27 comments#2)

["Jim Sermersheim" <jimse@novell.com>]

what about:
Diagnostic messages typically supplement the resultCode with additional
information.

Jim

>>> Hallvard B Furuseth <h.b.furuseth@usit.uio.no> 11/8/04 11:32:48 AM
>>>
Partial reply:

Jim Sermersheim writes:
>>>> Hallvard B Furuseth < h.b.furuseth@usit.uio.no > 11/7/04 7:00:33
PM
>>Jim Sermersheim writes:
>>>>> Hallvard B Furuseth < h.b.furuseth@usit.uio.no > 10/29/04
1:09:56
>>>>
>>>> I may have mentioned this before, but I can't find it in the
archive:
>>>> It might be useful to suggest or RECOMMEND either to treat
>>>> diagnosticMessages as supplements to the result code in error
>>>> messages, or to recommend the opposite (diagnosticMessages
intended
>>>> to stand alone without displaying the result code). I think
common
>>>> practice is the former, but I don't really know.
>>>
>>> I don't think you mean the disgnosticMessage should be used in
addition
>>> to resultCode in determining a course of action. So are you saying
we
>>> should describe behavior between a client application and a human
user?
>>
>> Right. Inform clients that display disgnosticMessage if they
>> also need to display the resultCode (or preferably an explanation of
it).
>>
>> And therefore, also tell servers if the disgnosticMessage, if any,
needs
>> to contain the information conveyed by the result code.
>
> I don't like the first comment. I think [Protocol] is in the
business
> of explaining how the protocol works rather than client
applications.

Good point.

> Though I do note that it says "Implementations MUST NOT display nor
> attempt to decode an attribute value if its syntax is not known"

And a few "Client implementors should note...".

> For the second comment, how about: "Diagnostic messages typically
> convey information pertaining to the value of resultCode"

Better wording, wrong words:-) Information pertaining to the _value_
of
the result code sounds to me like explaining what that value means in
general. I think I got that part right - information supplementing the
result code.

And I still wonder if it's worth to expand it to RECOMMEND
"information
supplementing rather than including the result code" (a bit strange
wording, I admit). Or "information which is intended to be displayed
in
addition to rather than instead of an explanation of the result code",
if that doesn't get too close to what clients should do again.

-- 
Hallvard