Hi Chuck, > A user guide would be nice, but I'd argue that having > accurate and useful javadoc would be much, much more helpful. > > For example, a coworker was implementing something that > handled PUT - he overrode handlePut() instead of put(). > Looking at the Javadoc, its not clear why you would use one > vs. the other. In fact, without looking at the code, I have > no idea why you would use one over the other.
On this precise example, it seems that those handle*() methods could be removed from Resource, with the logic moved to Finder. The extra flexibility they provide doesn't seem useful enough to justify the overhead. I've entered a RFE: http://restlet.tigris.org/issues/show_bug.cgi?id=361 > There are dozens of other examples I could give - there are > just too many entries where the description is simply just a > restatement of the method name with no clue how it relates to > anything else. > > It would also be useful if there were more explicit > references to HTTP instead of just using the generic REST > terminology. Often, the REST terminology is way too vague - > when I'm trying to interoperate with someone else, I'm > operating at the HTTP level, not the REST level, so I need to > know precisely what impact various methods have on request or > response methods. For example, it would be nice if > Response.setRedirectRef actually said that it sets the > Location header and whether it does anything else. I agree, good points. I've entered a new RFE: http://restlet.tigris.org/issues/show_bug.cgi?id=362 Thanks, Jerome
