Rethink `getraster` docstrings

[tiemvanderdeure]

Two issues with the way the docstrings of this package are currently organised:

1. Typing ?getraster current prints 17 separate docstrings for a total of 1696 words.
2. Precompilation outputs a warning because the docstring first is defined in interface.jl and then overwritten all those other 16 times.

Probably organising it like this made sense at some point, but I think there must be better ways to do this.

A proposal would be to migrate all the dataset-specific docstrings to their types (WorldClim, ModisProduct etc.) and only keep a single general for getraster that explains the general pattern and then refer to types that have docstring with other examples.

[rafaqz]

Yes its awful, so much scrolling to find what you need. We really need to connect the docs to the types.

But its not so easy to connect specific documentation to type combinations like WorldClim{Weather}. So they will all have to be lumped together under WorldClim, so still a bunch of scrolling required.

We can separate them it it the constructed type is called - like ?WorldClim{Weather}() because we can specifically document those - as function signatrues get their own docs. It might even be worth using that syntax to get that?

You can see how the REPL ? gets docstrings here:
https://github.com/JuliaLang/julia/blob/30cb68ef75c85061fb75c16653c2584089bcc9b6/stdlib/REPL/src/docview.jl#L259

And also just explore the Base.Docs module

[tiemvanderdeure]

I'm not sure if ?WorldClim{Weather}() is the way to go. Being redirected to a different docstring twice (from getraster to WorldClim to ?WorldClim{Weather}()) seems a bit excessive.

Maybe we can somehow make a single docstring for all the different signatures of WorldClim - since many of them use the same keywords. With a table that shows which types use which keywords or something?

[rafaqz]

Sounds good to me! But I was thinking to remove the getraster docs and just doc the types

[tiemvanderdeure]

I was thinking a single getraster docstring could be convenient, with the general idea and then referring to each of the types for the implementation

[rafaqz]

For sure. But it will be huge