gdal
gdal copied to clipboard
docs.rs should include `array` feature
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.
As a reference, the georust/proj crate does two things to document feature specific methods:
- enables features for the docs build (src):
[package.metadata.docs.rs]
features = [ "proj-sys/nobuild", "network", "geo-types" ]
rustdoc-args = ["--cfg", "docsrs"]
- 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:
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.
I really like the idea and I also think we should add these cfg_attr
s 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.
the array feature is really just a conversion method from the Buffer
to an ndarrray. Adding array to docs is a good idea.