On Mon, 2019-12-30 at 13:13 -0500, Gary Gregory wrote: > On Mon, Dec 30, 2019 at 12:11 PM Michael Osipov <[email protected]> > wrote: > > Am 2019-12-30 um 16:56 schrieb Oleg Kalnichevski: > > > On Mon, 2019-12-30 at 01:03 +0100, Michael Osipov wrote: > > >> Folks, > > >> > > >> just noticed HttpMultipartMode which mentions: /** RFC 822, RFC > > >> 2045, > > >> RFC 2046 compliant */ > > >> > > >> But RFC 822 has been superseded by RFC 2822, superseded by RFC > > 5322 > > >> and > > >> updated by RFC 6854. > > >> So have 2045 and 2046 updated by others. > > >> > > >> Also BROWSER_COMPATIBLE IE 5.0 and earlier? Is this mode still > > >> relevant? > > >> > > >> Would be nice of someone can drop off a comment or better yet > > update > > >> docs if code has been modified. > > >> > > > > > > The HttpMultipartMode javadocs correctly reflect the actual state > > of > > > MIME specification conformance. > > > > > > HttpMultipart has been built and reviewed against RFC 822, 2045 > > and > > > 2046. Any reference to newer specifications would be factually > > wrong > > > and deceitful. > > > > > > What I did thought to improve and simplify the API was removing > > > references to any specific RFCs from the HttpMultipartMode enum > > values > > > and replacing them with more neutral LEGACY, STRICT and EXTENDED: > > > > > > > > https://github.com/apache/httpcomponents-client/commit/1f2d7d7e85679f37b9be2bff80ac0dbc46405376 > > > > > > If at any point we upgrade to newer specifications we would not > > need to > > > change the enum itself. > > > > Ah, thanks for the enlightment. > > > > Do you think removing explicit RFC numbers helps the user better > > to > > understand what a mode supports?
I think it is actually better. I often have difficulty remembering what those RFCs were all about. Not to mention every time an RFC gets superseded by a newer one it necessitates class deprecation and renaming. The actual RFC conformance should be stated in the javadocs. > > @Gary, what is your opinion. > > I think the Javadoc should document what the code does now. If it > implements RFC n, it should say that "I implement RFC n". If there > exists RFC n+1, n+2 and so on, then the Javadoc can either say > nothing more or state that it knows about newer RFCs but does not > implement them. Sometimes less is more. Agreed. Oleg --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
