Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
[FR] Add 'rates' tag to UGen arguments in help docs #4303
UGens support a variety or rates for argument inputs, but support for various rates across all of the UGens is inconsistent and undocumented for the most part. Adding a tag to the help docs could promote documenting supported argument rates.
A tangential benefit would be that if existing UGens are documented over time, it would put more eyes on source code to identify where UGens don't fully support all reasonable input rates, and bugs in the rates that are supported.
Description of Proposed Feature
In addition to the
Something else to consider as a part of this would be other possible values for triggered inputs, specifying whether the trigger will affect the current sample/block output, the next, or is interpolated for inter-sample accuracy. This addition would take a bit more consideration...
Plan for Implementation
In addition to supporting this tag in the help renderer, an important aid to adoption would be to include these tags in the auto-generated help template for undocumented classes. This would need to detect
I would imagine the already-existing UGen docs would remain as they are, but could be populated with this new field over time. It's relatively easy to identify supported rates by looking at the source, but there are many to document and would have to just be knocked out in batches, perhaps one source file at a time. I'm happy to contribute to this effort.
Nice idea! I agree with Julian that it should be class side, not doc side as this would be useful elsewhere.
Does it need to return an array for each arg? I wonder as ar does not necessarily mean that kr is okay or interpolated. This could also be done with the spec, i.e. ar-no-kr-interp or whatever
I think all should be done with a single symbol per slot. Then we have a good overview of what is unsystematic.
I'm not sure if we should add information of whether
Also maybe there can be labels like
There are some cases where
Thanks for considering this.
This is a great idea!
I'm not sure it's possible to capture all supported rated with a single Symbol per argument. This depends on the implementation and number of calculation functions in the UGen. I could be overlooking other uses for the rate specs which may be made more complicated by arrays, but arrays would be more precise in describing the functionality.
I think the following would cover most cases.
Am I missing any cases?
Rendering into the help file might look something like this (just a quick mockup in an image editor):
I'm not sold on these particular symbols, I chose these to avoid confusion with the rate methods. Other suggestions?
I'm not all that familiar with demand-rate. My understanding is that demand rate UGens only ever update at one rate, so there is no variation to document. Is this the case?
There would need to be clarification in the UGen spec for outliers, like the case of a UGen running at
Exceptional and broken cases can be documented in the argument description.
I see one of the goals of this feature is to work toward a UGen spec for proper rate handling. I like Julian's suggestion of a
When documenting the UGen's inputs, we need to also account for: