Docstrings can do wondrous things. Wikipedia describes a docstring as “a string literal specified in source code that is used, like a comment, to document a specific segment of code.” I’ve rewritten sine_arp() to demonstrate a theoretical docstring example:
def sine_arp(dur, amp, pitch, lfo_freq): '''Generates an arpeggiated sine tone. dur - Duration amp - Amp pitch - Pitch, in pitch-class format lfo_freq - Frequency of lfo arpeggiator output - Audio signal ''' self['dur'] = dur # Set life of instance notes = [0, 3, 7, 8] # List of half-steps arp = Wavetable.osc(1, lfo_freq, notes) # Cycle through note list pitch = cpspch(pitch) * 2 ** (arp / 12.0) # Modulate pitch with arp osc = Wavetable.osc(amp, pitch, sine(1000)) # Generate audio output osc # Return audio
The docstring is the string block between the matching triple quotes. It gives a basic description of what the function/opcode/unit generator does and descriptions for the inputs and output.
What are the advantages of building docstring capabilities directly into a computer music language?
One. A proper description of a function and its interface will allow other users to import and reuse code with ease, propagating a remix culture within the community.
Two. With a utility like the Sphinx Python Documentation Generator, complete documentation can be auto-generated in the form of HTML, PDF, LaTeX, etc. This gives users the opportunity to browse a library of synths, patterns, note generators without ever having to browse the code.
Three. They can provide interactive help from within an integrated development environment. For example, if your cursor is resting in the middle of a function, the description can automatically be displayed from somewhere within the IDE.
Four. Imagine if a visual GUI environment, such as Max or PD or Reaktor, was built
on top of with slipmat. Docstring data could automatically be relayed to the visual object, as seen in the picture above. Furthermore, I have a hunch that if slipmat is designed properly, than all text function definitions could be visual objects, and vice versa, without modificaiton.
Question: Are there any other music languages that utilize a Docstring-like system. If so, I want to study them.