gdal icon indicating copy to clipboard operation
gdal copied to clipboard

docs.rs should include `array` feature

Open msalib opened this issue 3 years ago • 3 comments

It would be nice if we enabled at least the array feature for docs.rs by adding this to Cargo.toml:

[package.metadata.docs.rs]
features = ["array"]

Perhaps adding datetime to that list would be good as well.

The goal here is that someone looking at docs.rs should know that the array methods actually exist because otherwise, they're very easy to miss.

msalib avatar Oct 18 '21 20:10 msalib

As a reference, the georust/proj crate does two things to document feature specific methods:

  1. enables features for the docs build (src):
[package.metadata.docs.rs]
features = [ "proj-sys/nobuild", "network", "geo-types" ]
rustdoc-args = ["--cfg", "docsrs"]
  1. annotates each feature gated function/object (src)...:
    #[cfg_attr(docsrs, doc(cfg(feature = "network")))]
    #[cfg(feature = "network")]
    pub fn enable_network(&self, enable: bool) -> Result<u8, ProjError> {
            // implementation ellided...
    }

...which then renders the feature requirement nicely on the generated proj docs like this: Screen Shot 2021-10-18 at 1 47 18 PM

step 2 feels a little redundant to write, but I think it's really helpful for the doc consumers - otherwise they might wonder why they can't call the method that they see in the docs.

michaelkirk avatar Oct 18 '21 20:10 michaelkirk

I really like the idea and I also think we should add these cfg_attrs at the same time.

Maybe we can save some time in the realization if we decide on this first: https://github.com/georust/gdal/issues/169 But nevertheless, it should be a manageable effort.

ChristianBeilschmidt avatar Oct 19 '21 05:10 ChristianBeilschmidt

the array feature is really just a conversion method from the Buffer to an ndarrray. Adding array to docs is a good idea.

jdroenner avatar Oct 19 '21 07:10 jdroenner