Add usage examples to docs

[theotherphil]

Checked modules are complete.

• [ ] affine
• [ ] contrast
• [ ] corners
• [ ] definitions
• [ ] drawing
• [ ] edges
• [ ] filter
• [ ] gradients
• [ ] haar
• [ ] hog
• [x] hough
• [x] integral_image
• [x] local_binary_patterns
• [x] map
• [ ] math
• [x] morphology
• [ ] noise
• [x] pixelops
• [ ] property_testing
• [x] rect
• [x] region_labelling
• [ ] stats
• [ ] suppress
• [ ] union_find
• [ ] utils

[rmcqueen]

I will work on this.

Is it preferred to keep all example usages within examples/, or as an example comment, such as the example within src/region_labelling.rs::connected_components?

[theotherphil]

Great! Thus far I've only been adding doctests (so the latter). There's scope for adding more to /examples too - the main goal was improving the rustdoc documentation, but unit tests aren't great for showing visual effects so more /examples would also help.

Nearly all of the functions in this library have trivial APIs (pass in an image to transform, plus a few options, get an image back), so the doctests should ideally help clarify what the function does rather than just how to call it.

If you've not got much experience with rustdoc doctests, the lines starting # might be a bit confusing. These are hidden in the final docs, but we need them in most of the tests so that we can import the gray_image (and rgb_image, etc.) macros for use in the tests.

It might not be possible to add helpful doctests for all functions, but we can certainly add more than we have now. Most of the current doctests started life in the tests module in the file containing the function and were just moved into doctests with some comments added. There might be a few more tests lying around that can just be moved.

Thanks!

[mtn]

Where are rgb_image and similar macros defined? Sorry for resurrecting an old issue.

Edit: Oops, I see how they're working now. For some reason they weren't coming back in search.