This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.
http://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#AudioContext-section The methods for creating different AudioNodes use inconsistent naming conventions. Here is a list of current method -> type mappings: createBufferSource -> AudioBufferSourceNode createMediaElementSource -> MediaElementAudioSourceNode createMediaStreamSource -> MediaStreamAudioSourceNode createJavaScriptNode -> JavaScriptAudioNode createAnalyser -> RealtimeAnalyserNode createGainNode -> AudioGainNode createDelayNode -> DelayNode createBiquadFilter -> BiquadFilterNode createPanner -> AudioPannerNode createConvolver -> ConvolverNode createChannelSplitter -> AudioChannelSplitter createChannelMerger -> AudioChannelMerger createDynamicsCompressor -> DynamicsCompressorNode createOscillator -> Oscillator Apart from the inconsistently named AudioNode interfaces (see Bug 17407), the constructors also use a fair mix of: * Complete interface name, e.g. createDelayNode and createOscillator * With Node suffix, e.g. createGainNode, createDelayNode * Without Node suffix, e.g. createBufferSource, createConvolver * With key parts of the name dropped, e.g. createAnalyzer The only consistency I can see is that any occurrences of "Audio" in the interface names have been dropped in the create-method names. Suggestion: Include the entire interface name, possibly excluding Audio prefix and/or Node suffix (as long as it's the same for all methods).
(In reply to comment #0) > http://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#AudioContext-section > > The methods for creating different AudioNodes use inconsistent naming > conventions. Here is a list of current method -> type mappings: > > createBufferSource -> AudioBufferSourceNode > createMediaElementSource -> MediaElementAudioSourceNode > createMediaStreamSource -> MediaStreamAudioSourceNode > createJavaScriptNode -> JavaScriptAudioNode > createAnalyser -> RealtimeAnalyserNode > createGainNode -> AudioGainNode > createDelayNode -> DelayNode > createBiquadFilter -> BiquadFilterNode > createPanner -> AudioPannerNode > createConvolver -> ConvolverNode > createChannelSplitter -> AudioChannelSplitter > createChannelMerger -> AudioChannelMerger > createDynamicsCompressor -> DynamicsCompressorNode > createOscillator -> Oscillator > > Apart from the inconsistently named AudioNode interfaces (see Bug 17407), the > constructors also use a fair mix of: > > * Complete interface name, e.g. createDelayNode and createOscillator > * With Node suffix, e.g. createGainNode, createDelayNode > * Without Node suffix, e.g. createBufferSource, createConvolver > * With key parts of the name dropped, e.g. createAnalyzer > > The only consistency I can see is that any occurrences of "Audio" in the > interface names have been dropped in the create-method names. > > Suggestion: Include the entire interface name, possibly excluding Audio prefix > and/or Node suffix (as long as it's the same for all methods). How about being consistent by removing the "Node" suffix, leaving all the "create" methods the same, except for: createGainNode -> createGain createDelayNode -> createDelay createJavaScriptNode -> createScriptProcessor I'm less sure about the naming of "createScriptProcessor". Some have suggested that we might use other scripting languages than JavaScript, so that shouldn't be a part of the name.
(In reply to comment #1) > How about being consistent by removing the "Node" suffix, leaving all the > "create" methods the same, except for: > > createGainNode -> createGain > createDelayNode -> createDelay > > createJavaScriptNode -> createScriptProcessor > > I'm less sure about the naming of "createScriptProcessor". Some have suggested > that we might use other scripting languages than JavaScript, so that shouldn't > be a part of the name. I think we need to resolve Bug 17407 before moving forward with this one.
(In reply to comment #2) > (In reply to comment #1) > > How about being consistent by removing the "Node" suffix, leaving all the > > "create" methods the same, except for: > > > > createGainNode -> createGain > > createDelayNode -> createDelay > > > > createJavaScriptNode -> createScriptProcessor > > > > I'm less sure about the naming of "createScriptProcessor". Some have suggested > > that we might use other scripting languages than JavaScript, so that shouldn't > > be a part of the name. > > I think we need to resolve Bug 17407 before moving forward with this one. Now that 17407 is resolved, how do the two method name-changes sound?
(In reply to comment #3) > Now that 17407 is resolved, how do the two method name-changes sound? Given your suggestion, we'd get: createBufferSource -> AudioBufferSourceNode createMediaElementSource -> MediaElementAudioSourceNode createMediaStreamSource -> MediaStreamAudioSourceNode createScriptProcessor -> ScriptProcessorNode createAnalyser -> AnalyserNode createGain -> GainNode createDelay -> DelayNode createBiquadFilter -> BiquadFilterNode createWaveShaper -> WaveShaperNode createPanner -> PannerNode createConvolver -> ConvolverNode createChannelSplitter -> ChannelSplitterNode createChannelMerger -> ChannelMergerNode createDynamicsCompressor -> DynamicsCompressorNode createOscillator -> OscillatorNode This looks very intuitive to me. The only thing sticking out here are the three first nodes, where "Audio" is somehow in the node name (which seems right IMO), but not in the create* method name. I don't have any objections to that (shorter names = good thing™), other than the possible loss of distinction between Audio/Video Media sources that you mentioned in Bug 17407. Any thoughts?
(In reply to comment #4) > (In reply to comment #3) > > Now that 17407 is resolved, how do the two method name-changes sound? > > Given your suggestion, we'd get: > > createBufferSource -> AudioBufferSourceNode > createMediaElementSource -> MediaElementAudioSourceNode > createMediaStreamSource -> MediaStreamAudioSourceNode > createScriptProcessor -> ScriptProcessorNode > createAnalyser -> AnalyserNode > createGain -> GainNode > createDelay -> DelayNode > createBiquadFilter -> BiquadFilterNode > createWaveShaper -> WaveShaperNode > createPanner -> PannerNode > createConvolver -> ConvolverNode > createChannelSplitter -> ChannelSplitterNode > createChannelMerger -> ChannelMergerNode > createDynamicsCompressor -> DynamicsCompressorNode > createOscillator -> OscillatorNode > > This looks very intuitive to me. The only thing sticking out here are the > three first nodes, where "Audio" is somehow in the node name (which seems > right IMO), but not in the create* method name. > > I don't have any objections to that (shorter names = good thing™), other > than the possible loss of distinction between Audio/Video Media sources that > you mentioned in Bug 17407. Any thoughts? My thinking here was that the create() methods are in the "namespace" of the AudioContext, and thus it's implied that we're dealing with audio, and the clarity gained by the shorter name was worth it. By contrast, the node/class names are in the global namespace and so I wanted to make that distinction.
(In reply to comment #5) > My thinking here was that the create() methods are in the "namespace" of the > AudioContext, and thus it's implied that we're dealing with audio, and the > clarity gained by the shorter name was worth it. By contrast, the > node/class names are in the global namespace and so I wanted to make that > distinction. Ah, good point. Looks fine to me.
Fixed: https://dvcs.w3.org/hg/audio/rev/233781dbb864
Looks good. A minor miss though: createGainNode is still being used in an example (1.2. Modular Routing). By the way, should appendix C (Web Audio API Change Log) still be maintained or should it be dropped? It seems to lack most recent updates.
(In reply to comment #8) > By the way, should appendix C (Web Audio API Change Log) still be maintained > or should it be dropped? It seems to lack most recent updates. I gather it's updated only when we do a /TR publication. The up-to-date changelog remains http://dvcs.w3.org/hg/audio/ (which, admittedly, also includes the change log for our other docs)
Setting to reopened, since section 1.2. is still wrong (see https://www.w3.org/Bugs/Public/show_bug.cgi?id=18332#c8 ).
(In reply to comment #8) > Looks good. A minor miss though: createGainNode is still being used in an > example (1.2. Modular Routing). I have spun off Bug #21580 to track this particular issue. Closing here.