Inconsistency Implementation vs. JavaDoc
chludwig-haufe opened this issue · comments
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
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.