API documentation: undocumented parameters & methods

[sadielbartholomew]

Hi. Though the API documentation is quite detailed, towards the openjournals/joss-reviews#2407 review, I have noticed two aspects that I think are barriers towards the 'Documentation -> Functionality documentation' review requirement being deemed satisfactory:

1. There are some parameters for a number of methods in the IPART API that are not documented (see examples below);
2. Not all of the util modules, and not all methods from those that are present, are documented. This is indicated via '(selected parts)' after the names of the utils.funcs.py & utils.plot.py pages in the page listings, but there is no explanation as to why the modules under utils in the directory hierarchy are only partially documented.

Examples for (1)

For example (though it may be the case for other modules so please check), looking at the API reference pages for thr.py and AR_detector.py I notice that:

• the verbose parameter appears in the signature of many methods but is not documented in any of them (though perhaps by name quite obvious in purpose, I think it is still best to state it so users can be sure);
• thr.rotatingTHR is stated to accept a parameter kernel but that is not described;
• no parameters are documented for AR_detector.cart2Wind, AR_detector.plotGraph or AR_detector.wind2Cart despite their signatures suggesting they all accept parameters;
• AR_detector.prepareMeta has parameters ntime, nlat, nlon which are only described in reference in the documentation of other parameters;
• AR_detector.findARs has the parameter param_dict documented, but it does not appear in the signature for that method, so it is not clear whether it is indeed a parameter that is accepted (or has any influence) on it.

Resolution

Please can you address the following points to resolve the above:

• If a module is not documented, or certain functions within it are not, please either:
  • document these (if you are intending to but have not yet got this done); or
  • provide a brief explanation as to why they are deliberately not being documented, e.g for utils/funcs.py you could just state something like (guessing a potential reason), "Only some functions from this module are documented. The other undocumented functions are intended as private functions, not to be exposed to the user."
• For all methods that you do document, ensure all parameters appearing in the signature are explicitly (i.e. not just referenced in the description for other parameters) described. This includes the examples outlined above, but they are only from the two pages referenced, so it is not an exhaustive list to address.

Thanks.

[Xunius]

@sadielbartholomew Thanks for the comments.

Please checkout the commit and this commit addressing these issues.

Regarding the documentation for other functions in utils.func.py and utils.plot.py, I added doc strings for them in another branch (netcdf), but I was not advised to merge until review is finished, as I made a dependency change in that branch.

[sadielbartholomew]

Thanks @Xunius. I will get back to you later today about this, & to continue my reviewing, but from what I can see from a quick look that all sounds good & I can likely close the Issue later on after the new commits you have made.

[kbarnhart]

~Linking this to the JOSS review thread: openjournals/joss-reviews/issues/2407~ Apologies. I now see that @sadielbartholomew already did this.

[sadielbartholomew]

Thanks @Xunius, I have checked the status of the documentation again and you have addressed my feedback well with those new commits & others, so I can close this. I am happy to tick the 'Functionality documentation' criteria off the checklist, especially given the new detailed sections for each of the four core functionalities (the 'Perform the THR computation on IVT data' page, etc).