search

damnhandy / Handy-URI-Templates

A Java URI Template processor implementing RFC6570
https://damnhandy.github.io/Handy-URI-Templates/
Other
203 stars 37 forks source link

Inconsistency Implementation vs. JavaDoc #57

Closed chludwig-haufe closed 6 years ago

chludwig-haufe commented 7 years ago

The static "constructor" UriTemplate#fromTemplate(UriTemplate) returns a UriTemplateBuilder object. However, its JavaDoc comment says (in version 2.1.6):

Creates a new {@link UriTemplate} from a root {@link UriTemplate}. This
method will create a new {@link UriTemplate} from the base and copy the variables
from the base template to the new {@link UriTemplate}.

The doc does clearly not match the implementation. If I am not mistaken then the implementation of UriTemplate#fromTemplate(UriTemplate)has the same effect as UriTemplate#buildFromTemplate(UriTemplate). (Actually, there is a subtle difference in the implementation of the two methods; but as far as I can tell they produce the same result. The latter seems more efficient, though.) The overloads of the two methods that take a template String, respectively, have different return types. I therefore suspect that the doc states the intended behavior. But "fixing" the implementation now is a breaking change.

Either way, documentation and implementation should be consistent. If my suspicion is correct, then the doc should say that the method is a duplicate. It's still possible to add a new static constructor that returns a UriTemplate.

Cheers, Christoph

damnhandy commented 6 years ago

Yeah, this was a little sloppy on may part, so thanks for pointing that out. I made some changes so that it's more concise. Going forward, UriTemplate#buildFromTemplate(UriTemplate) is the one to use and UriTemplate#fromTemplate(UriTemplate) will be deprecated as the do the same thing.