1085731 - Documentation in MimeHeaderParser.h is incorrect, and uses "header" to mean multiple things

Status: ASSIGNED

(MailNews Core :: MIME, defect)

Description

[Kent James (:rkent)]

Per jcranmer, in Bug 842632 later versions changed the definition of methods, but those changes did not get reflected in the documentation. The whole plan involving DecodedHeader and EncodedHeader does not seem to be reflected in the documentation.

Also in reading the documentation, "header" (which is already ambiguous since it can mean an nsIMsgDBHdr object) is also used to describe the new msgIAddressObject as well as strings, which increases the confusion.

This really needs fixing, since we've been maintaining higher standards but those were violated in this landing. Even though I was involved in some of the original code comments, I now find (months later) code using these methods very difficult to review because of the incorrect and confusing documentation.

Comment 1

[Joshua Cranmer [:jcranmer]]

Attachment: Correct documentation

How does this documentation look to you?

Comment 2

[Kent James (:rkent)]

Try to understand this, I hit an issue trying to understand what an msqIAddressObject is. The documentation says:

" * In general, the attributes of this interface are always meant to be in a form
 * suitable for display purposes, and not in a form usable for MIME emission. In
 * particular, email addresses could be fully internationalized and non-ASCII,
 * RFC 2047-encoded words may appear in names, and the name or email parameters
 * are unquoted."

How is an RFC 2047-encoded word "suitable for display purposes"? I read "RFC 2047-encoded words may appear in names" to mean that non-ASCII text can appear either directly, or encoded like =?...?=  In trying to use and review patches with these interfaces, the issue that keeps coming up is which objects are supposed to have which encodings. From the documentation, I cannot tell if the "name" attribute of the msgIAddressObject is supposed to have non-ASCII text in RFC 2047 format or not.

That is because of the two issue: 1) It seems it is supposed to be encoded, but that is not "suitable for display" which is a contradiction. 2) "may" confuses whether this handles either case. Perhaps I can use either and it will automagically make it right?

Please clarify. I think the best path forward is going to me for me to try to understand the documentation, correct what I find confusing, then ask for your review.

Comment 3

[Jorg K (CEST = GMT+2)]

Comment on attachment 8508367 [details] [diff] [review]
Correct documentation

No action in three years, I'll take a look.