Hi again,
Actually, it appears that all the mentioned properties are documented in the API help topic about the ReviewSummaryRequest interface. This interface is used as the argument type for the getReviewSummary method:
Greetings,
I strongly disagree; there is absolutely no information about what is required for that call. There is no information about what 'active' means, or why passing true and false returns the exact same data, but in a vaguely different order. Or why passing ANYTHING that I've tried for clientGuid results in a NullPointerException. Or what valid values for clientBuild are, or even WHY those values are required to get a ReviewSummary.
Your documentation for the ReviewService.getReviewSummary call in your own post (which I read many times trying to understand this) implies that just reviewId, clientBuild and clientGuid are required, but clientGuid isn't, active is, and that's not called out. Your JavaDoc is completely lacking for updateToken, active, and consolidationMethods, all of which are also apparently parameters, except that reviewId, clientBuild, and active are the only ones that are required. I have no idea what those other parameters do, nor does anyone who isn't on your team and has access to the source code.
It is impossible to implement to that documentation without flailing around, guessing at valid values, and tripping on the solution. I'm sure it's easier for you folks, because you already know what they all mean, but your documentation makes no attempt to explain those parameters. This is endemic in your docs.
'Documentation' that consists exclusively of:
public interface ClientBuildRequest
A request to get client build number
public interface ClientGuidRequest
A request to get client guid number
is half-hearted JavaDoc at best, and probably machine generated. You need to explain what valid values are, and explain what it's used for, so the callers can have any marginal idea of how to build something for it.
Properties are not documented unless an unrelated caller understands which to use, and why to use them. Those properties, and that call (one of the most important in your set of calls) are not documented.
I really do appreciate the API, and it's not the worst I've had to reverse-engineer, but the documentation DEFINITELY needs to be written, especially for that critical call.
-- Morgan
