On Mon, Dec 30, 2019 at 12:11 PM Michael Osipov <micha...@apache.org> 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 am currently looking at the RFCs > myself for an inhouse REST API and just having abstract defitions is a > bit too far away for my taste. > > @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. Gary > > But I will be happy with both approaches as long as documentation is > correct. > > Michael > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > >
