Originally posted by: WPettersson

I've been working with the docloud API recently for a few things, and I've got some feedback and questions.

Firstly, according to Pypi, the docloud package is under the Apache license, is this correct? If so, I can happily host a project on Github or similar and take care of at least some of these issues.

The issues I have:

* The documentation (at https://api-swagger-oaas.docloud.ibmcloud.com/api_swagger/pythondoc/index.html) has odd formatting. There are odd blockquote tags throughout the HTML, which makes the documentation hard to follow. These are probably due to the newlines in the docstrings, and whatever documentation generator you are using. I'm guessing sphinx, but could be wrong.

* JobSolveStatus is a class in the package, but is not referenced anywhere. It has no static methods. It seems completely pointless.

* JobClient.wait_and_get_solution only looks for solution.json, it doesn't look for other file formats for the solution. JobClient.execute does things better, it iterates over all extension types, but maybe detecting the solution file type would be nicer still.

* The "parameters" is barely explained. The first time it appears in the documentation, a few possible keys are listed but with no explanation. Every other time the "parameters" option shows up, it's just called a "A dict with additional job parameters." which is nigh on useless. On top of this, the keys that are listed often need testing to work out what they actually are. For instance, oaas.timeLimit is the time limit for the job, which is obvious. However, the time limit is specified in milliseconds, which is not explained anywhere on the Python documentation. Also, are there really use-cases where time limits do need millisecond accuracy? Seems an odd decision for a cloud-based service.

Anyway, those are the obvious things that have come up so far, I'd like to help fix them if I can, if not I can just keep posting the issues I find.

Originally posted by: Viu-Long Kong

William,

Thanks for your feedback. The dev team will have a look at your issues and fix them.

JobSolveStatus is an enum in python, and we hopped that the built-in mecanism from Enum to convert strings to an enum would remove the hasle of doing this manually:

job = client.get_job(jobid)
solveStatus = JobSolveStatus[job['solveStatus']]

cf https://docs.python.org/3/library/enum.html#programmatic-access-to-enumeration-members-and-their-attributes

(we use the Enum34 package on python 2 to have the same behaviour)

Of course, if you don't want to use Enum or do not use them, you can use the string value.

Concerning the parameters parameter, you have a list of accepted parameters in the general documentation of the DOcplexcloud service (https://developer.ibm.com/docloud/documentation/docloud/job-parameters/ )

Regards,

Originally posted by: WPettersson

Thanks for that feedback Viu-Long,

The usage of JobSolveStatus makes more sense now that you've explained it, but perhaps that information should also be in the documentation explaining its usage. The same goes for the parameters parameter, the documentation doesn't link to that list in the general documentation. Even just dropping that URL into the source for the class would be very useful.