In-file documentation

[kakearney]

This issue is part of the JOSS review (openjournals/joss-reviews#2497)

The current documentation lists the inputs and outputs for each function. However, the description of the input and output variables often provide only very minimal description, and not enough to avoid errors. All requirements for inputs (including class, expected size, and any limits of value) should be clearly stated. For outputs, fully describe the returned variables. In particular, describe the primary data structures, including all fields, their classes, and as much metadata as possible from the underlying data source (original name, units, etc).

For example, the function argo_build lists the syntax

[argo,matching_files] = argo_build(argo_dir,region,start_date,end_date,variable_list)

The example shows argo_dir as character array search path with wildcards; would a folder name work? (Answer: no) How about a cell array of specific file names? (also no). What happens if the specified path points to non-netCDF files? (Error using netcdflib, The NetCDF library encountered an error during execution of 'open' function - 'Unknown file format (NC_ENOTNC)'.)

The region input appears to be a row vector [latmin latmax lonmin lonmax]; will a column vector work? (yes) Does longitude have to be in either -180-180 or 0-360 (neither causes an error, but I didn't have enough Argo data to test further), and must lonmax be greater than lonmin if the region crosses the dateline? (yes, otherwise Index in position 1 exceeds array bounds. Error in argo_build (line 100)).

For the date inputs, the example shows date strings being used. What if I enter datenumbers instead? (Error using datenum (line 190), DATENUM failed.) How about a datetime? (Error using datetime/datenum, Too many input arguments.)

For the variable list, the example shows a cell array of strings. Will a character array work for a single variable? (Yes) How about a string or array of strings? (Yes). What happens if you specify a variable that isn't in the file? (Index in position 1 exceeds array bounds, Error in argo_build (line 100)).

The argo output is only described as a structure, and no description is provided for matching_files.

[lnferris]

I have gone through every file and expanded the in-file documentation (as well as the browser based documentation linked from the main readme).