Mysterious 'area' argument for `cmor_grid` in API reference

[mauzey1]

The API reference for cmor_grid has an argument named 'area' with the description: "array containing the grid’s area information (ndim)"

However, the function signature in the C API doesn't have this argument nor do the Fortran and Python interfaces. Is this a remnant from older versions of CMOR? The Fortran interface has "noarea" versions of the function suggesting it was once part of the original API.

@taylor13 @durack1 @doutriaux1 Can any of you confirm?

Since it is no longer used in the current API, it's mention should be removed from the documentation.

[taylor13]

I looked at the CMOR1 code ca. 2008 and the CMOR1 documentation and there is no user function to handle general "grids". In fact the documentation explicitly forbids anything but a rectangular latitude x longitude grid, which of course is stored differently from more complex grids.

The grid function was introduced later to treat more general grids and I suspect the option to include cell areas may not have been implemented but somehow made it into whatever the "signature" is.

For CMIP, cell areas are stored as one of the variables CMOR writes, just like all the other variables, so I don't think it needs to be recorded in every file along with "grid" information.