Rogues' gallery of... amusing documentation

Development
1

Just for fun – let’s make a catalog of documentation snips that … how to put it gently … are in need of some attention :laughing: Could even create a “good first issue” / “low-hanging fruit” issue based on this.

Exhibit A - SimpleNumber:fold2:

.fold2(aNumber: 1, adverb)
the folded value, a bitwise or with aNumber

“Bitwise”?

hjh

2 Likes
2

Not really amusing but IEnvGen doesn’t mention at all that its envelope is essentially i rate. Only sampled once in the constructor then held. Nothing modulatable. In general, some kind of documentation review properly documenting what is and what isn’t modulatable in various UGens would be desirable, but it’s a probably a big job and many UGens, especially from plugins, even lack more basic usage documentation. Probably because most come from various academic papers. (Speaking of which, the word “modulatable” also sounds pretty academic, but it’s what is used in the help files.)

1 Like
3

The documentation says for the env parameter: “an instance of Env (this is static for the life of the UGen)”. There are a few ugens that have intricate examples instead of simple usage, you can discuss improvements. Documentation is like a signal, it’s indeed modulatable.

4

One that’s hard on my brain: all the valueEnvir, inEnvir, use, valueWithEnvir etc. Hard to remember what each one does.

5

And something today:

SynthDesc.outputData
Returns an array of events with information about any UGens that write to a bus (such as Out etc.). This includes the rate and number of channels of the UGen. If its first input is a control, also the corresponding control name is provided.

With this example provided:

a = SynthDef(\x, { |out, freq = 440| Out.ar(out, SinOsc.ar(freq)) }).add;
a.desc.outputData;
a = SynthDef(\x, { |out, freq = 440| Out.ar(out + 7, SinOsc.ar(freq)) }).add; // no controlName in this case
a.desc.outputData;

Actual output is exactly the same for both those lines:

-> a SynthDef
-> [ ( 'rate': audio, 'numChannels': 1 ) ]
-> a SynthDef
-> [ ( 'rate': audio, 'numChannels': 1 ) ]

So I have no idea what that is talking about or trying to show…

6

Probably a bug then. SC does have a few bugs here and there, just like any software… with this one, I don’t remember anyone using outputData for years (I didn’t even know this method existed!), so it’s unsurprising that a problem hasn’t been noticed. (FWIW it may not be easy to trace back to the control name.)

hjh

7

And of course the current “star of my life” Control. Its help page freely mixes Control.names with NamedControl examples failing to even mention that these live in separate namespaces.

NamedControl’s page says just “NamedControl allows to reuse existing control names”. Meaning presently: only “reuse” (i.e. access) those that were issued through its own interface, but not otherwise.

8

As I had to fix something that used InBus today. The help page of that was… unhelpful:

InBus: Return a range of channels from a bus, irrespective of node order

Node order, huh?

InBus provides a simple interface to the signal on a bus, crossfading between adjacent values.

I guess it means between adjacent busses. But where is the xfade param in the interface?

InBus.ar(bus, numChannels, offset: 0, clip)
InBus.kr(bus, numChannels, offset: 0, clip)
Return a new instance with the respective rate. If the bus rate doesn’t match the signal is converted. Multi channel arguments expand.

Mmmmkay? Is rate the key feature here?

Arguments:
bus
An instance of Bus

numChannels
Number of output channels

offset
Offset to the starting index in the bus.

clip
If clip is set to ‘wrap’, the indices into the bus will not be clipped to the last bus channel, but will wrap around.

Returns:
A UGen output, usually an array of UGens or, if the arguments are arrays, an array of arrays.

What it actually does is in fact simpler to explain by:

b = Bus.audio(s, 3)
InBus.ar(b)
// -> [ an OutputProxy, an OutputProxy, an OutputProxy ]

InBus.ar(b, 2)
// -> [ an OutputProxy, an OutputProxy ]

InBus.ar(b, 4)
// -> [ a XFade2, a XFade2, a XFade2, a XFade2 ]

The undocumented nil numChannels feature is used a bit in the class library to auto-size a bus reader.

9

It is quite common to see this kind of description throughout SC:

WhiteNoise
White noise.

FFT
fast fourrier transform

Pfunc
function pattern

When you are an advanced user you don’t even pay attention to these description, but for beginners this represents unnecessary rocks in the middle of the learning path. I think it would be nice if changes are introduced to clarify specificities or to present ideas more didactically:

WhiteNoise
random signal with equal power at all frequencies.

Description
this UGen generate a white noise by the method of … which constitutes a pseudo random number…
In discrete time, white noise is a discrete signal whose samples are regarded as a sequence of serially uncorrelated random variables with zero mean and finite variance[WIKI]; this means that using WhiteNoise as modulation signals implicates in…

FFT
short time fast fourrier transform

Pfunc
evaluates an arbitrary user specified function at each call

2 Likes