Better documentation

[LukasKalbertodt]

I hate to be that guy, but this crate could very much use more documentation. For example, taking a look at https://docs.rs/simdnoise/3.1.1/simdnoise/struct.RidgeSettings.html, most methods are not documented and the type itself isn't documented as well. While "ridge noise" and all of the methods might be self explaining to someone who already has a deep understanding of different noise algorithms, it would really help if documentation would explain the basics.

[jackmott]

Including some images in the docs would help a lot, I'm looking into how I could do that. In the meantime anyone looking for help can use this handy tool a buddy of mine made:

https://github.com/Auburns/FastNoiseSIMD/releases

It lets you preview very noise options and settings. My library won't produce identical images as his but they will be very similar. We could build our own preview app as well. PRs welcome of course!

[psotos]

@jackmott Any progress on this? I am using a different noise library currently (https://docs.rs/noise/0.6.0/noise/index.html), but I am considering changing that library to this one.

[nickeb96]

Please consider adding more information to the documentation. The noise variants do not have any information on what they do or how they differ from one another. Some of these are easy enough to google, but I have no idea what the difference between CellularSettings and Cellular2Settings are.

Also many of the functions do not explain what they do. I have no idea what "lacunarity" or "gain" or "octaves" are. I've been googling around to try and understand these and looking at the source code, but it would be nice if that wasn't necessary.

I like this crate a lot and it looks really powerful, but additional documentation would go a long way as far as usability goes.

[jackmott]

If anyone knows of a way to get images that show up in rustdocs reliably, I'd love to add little thumbnails for each type. I don't want to have to link to a separate website that I have to maintain though. Perhaps I could set up something within github, and link to that though? thoughts?

in the meantime, this windows app is really handy for experimenting with noise types and settings: https://github.com/Auburns/FastNoiseSIMD/releases

I can't think of any useful way to describe these things in words.

[nickeb96]

It looks like you can have links to images in the docs. It uses markdown so it would just be ![](link-to-image) in the docstring above a type or function definition. I just checked to see if images can be hosted locally on docs.rs but it looks like there is currently no support for it. You could instead host the images directly on github like you mentioned and just link to those. Maybe under a directory like "rust-simd-noise/examples"? You could also potentially put source code samples to create the images in that directory too.

It might look something like:

/// Fractal Brownian Motion is ...
///
/// Here's an example image of 2d fbm noise:
/// ![](https://github.com/jackmott/rust-simd-noise/examples/fbm/output.png "fbm example image")
/// The above image was created with these settings [here](https://github.com/jackmott/rust-simd-noise/examples/fbm/main.rs "fbm example code").
#[derive(Copy, Clone)]
pub struct FbmSettings {

(inserted right before line 451 of src/lib.rs)

You could look at sites like wikipedia for wording function docstrings. I took this directly from wikipedia (https://en.wikipedia.org/wiki/Lacunarity):

"Lacunarity is a specialized term in geometry referring to a measure of how patterns, especially fractals, fill space, where patterns having more or larger gaps generally have higher lacunarity."

Unfortunately I don't have a windows computer so I can't use the tool you mentioned.