On the Importance of Docstrings

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.