Comments (10)
This came up when working on #602 where the non-mut
functions double the amount of work I would have to do.
from imageproc.
I expect the non-mut versions will be far more widely used, with the _mut versions existing solely to allow users to control allocations if this matter for their use cases. I'm not a fan of removing the more ergonomic and more used (I assume) versions of functions.
We should standardise on having detailed documentation on the non-mut versions and linking to this from the _mut versions.
In theory the generation of the _mut versions could be automated via a proc macro but this feels unlikely to be worth the extra complexity or compile time.
from imageproc.
Judging by some grep.app searches it varies quite a bit.
dilate shows only the mut version is used.
map_pixels shows both the mut version and the non-mut version.
from imageproc.
In theory the generation of the _mut versions could be automated via a proc macro but this feels unlikely to be worth the extra complexity or compile time.
I think a proc macro would solve my issues with maintainability and help with standardization, I don't think the added compile time would be noticeable for such a simple proc-macro, the complexity would be mostly a one-time cost on the implementation of the proc-macro and should be very easy to use after its created perhaps?
from imageproc.
Nevermind, I tried implementing the proc-macro and I needed to use a lot of heuristics when generating the non-mut function signature such as choosing a return type based on the input image type which could get very complicated very quickly when generics are involved.
What about switching the documentation to the mut version rather than the non-mut function seeing as that is the "real" function whereas the non-mut variation is simply a useful helper function? Then we could standardize the documentation of the non-mut functions as:
/// An immutable version of [`erode_mut`].
This function clones the given image, then runs the operation on the cloned image and then returns the mutated image.
This documentation could be generated from a regular macro_rules!(erode_mut)
as well which reduces the amount of duplication.
from imageproc.
Itβs more convenient to write doctests for the non-mutating variants, so Iβd flip your suggestion. But the idea of generating the _mut docs via a macro is a good one.
from imageproc.
But is it a good idea to be teaching new users to use the less-efficient functions? That may cause users to use the non-mut variations even if they don't need the original image anymore since those are the functions with examples. That doesn't really fit with rusts fast-by-default design imo.
from imageproc.
The two versions of each function will be next to each other in the documentation so anyone who wants to re-use an allocation can quickly spot that this is possible.
from imageproc.
Fair point, I'll start a PR standardizing all the mut/non-mut functions using a macro then π After that, I'll be able to rebase and continue #602 which might become easier.
from imageproc.
Sounds good, thanks.
from imageproc.
Related Issues (20)
- Try using doc_auto_cfg to automate addition of docrs attributes
- Rename `imageproc::map::map_colors()` to `map_pixels()` HOT 2
- Another doc-macro for parallel variations of functions?
- `Rect` refactors HOT 2
- Add filter benchmarks for kernels larger than 3x3
- Add hardcoded filter3x3 function to benchmark current generic filter function against HOT 19
- Switch `imageproc::Rect` to `image::Rect` HOT 3
- `Laplacian` from `master` is wrong HOT 4
- Check for any functions missing tests
- Use `Kernel` by `ref` HOT 2
- Document release process
- Agree a sensible API for filtering so we can reduce the risk of frequent breaking changes to signatures HOT 3
- Fix filter performance vs simple hardcoded implementation
- Add Tags for all previous releases where possible HOT 2
- Decide module layout for new imageops functions HOT 1
- how encode drawed image to [u8] ? HOT 6
- Rounded corners on rectangles and images HOT 4
- Projection matrix for rotation is weird
- Add `#[must_use]` to all non-mut image processing functions
- Broken links in docs.rs documentation
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from imageproc.