Documentation/examples

[alextbradley]

I am currently working through the documentation. Some notes below (apologies if these should be obvious to me, I am coming at this as a non-expert in the specific topic!)

• For each of the types, it would be good to add explicit examples. You should also add explanation of the arguments in the constructor functions (e.g. what does [Ti::DataType] refer to?)
• It would be good to explicitly state that the types are the core 'calendar' objects that the package interacts with
• In the timedecode function, state what the format of the units string has to be
• Add an example for timeencode
• I know they are just wrapper functions for the Dates package, but why not just use CFTime for all of the accessor function documentations, rather than Dates for those down to nanosecond and CFTime for smaller?

In addition, it would be good to make the example usages more explicit (I'd suggest adding an 'examples' section to the documentation) and add some examples where the package is used to solve real world issues (at the moment the issues are quite abstract).

ref openjournals/joss-reviews#8487

[Alexander-Barth]

Thank you for your careful reading of the documentation and the very helpful suggestions!

For each of the types, it would be good to add explicit examples. You should also add explanation of the arguments in the constructor functions (e.g. what does [Ti::DataType] refer to?)

We added examples for all types. Also expanation for Ti, units and origin have be added/expanded.
https://juliageo.org/CFTime.jl/latest/#CFTime.DateTimeStandard

It would be good to explicitly state that the types are the core 'calendar' objects that the package interacts with

Thank you for the suggestion. This is done in
3b09f18

In the timedecode function, state what the format of the units string has to be

Explanation of the units parameter has been added summarizing the relevant part of the CF conventions:
https://juliageo.org/CFTime.jl/latest/#CFTime.timedecode

Add an example for timeencode

An example has also been added for timeencode :
https://juliageo.org/CFTime.jl/latest/#CFTime.timedecode

I know they are just wrapper functions for the Dates package, but why not just use CFTime for all of the accessor function documentations, rather than Dates for those down to nanosecond and CFTime for smaller?

In fact the function year, month, ... nanosecond are defined as method in Dates and only extended in CFTime for new types. Only the functions picosecond, ..., attosecond are specific to CFTime. The module prefix choosen by Documenter.jl reflects that even if the documentation of CFTime.year is requested (https://github.com/JuliaGeo/CFTime.jl/blob/47d964159c50af071ac2e83cad691f8306fe1b87/docs/src/index.md). It is also preferable that users code uses Dates.year rather than CFTime.year because the former is more generic (but both do actually work).

This discussion here seems to be related:
https://discourse.julialang.org/t/remove-inner-module-function-name-with-docs-in-documenter-jl/61617

It seems to be a design choice of Documenter.jl presumably made to promote generic code.

In addition, it would be good to make the example usages more explicit (I'd suggest adding an 'examples' section to the documentation) and add some examples where the package is used to solve real world issues (at the moment the issues are quite abstract).

I agree. I added the following example concerning CMIP6 which uses the CF calendar "noleap":
https://juliageo.org/CFTime.jl/latest/example_CMIP6/

Note that even if the function is called Dates.year in this example is uses the function defined in CFTime as it is applied on a type (DateTimeNoLeap) from CFTime.

[Alexander-Barth]

An additional basic usage example has been added.