18332 2012-07-19 13:40:33 +0000 Node creation method naming inconsistencies 2013-04-25 15:31:46 +0000 1 1 1 Unclassified AudioWG Web Audio API unspecified PC Linux CLOSED FIXED P2 normal TBD 1 mage crogers olivier.thereaux public-audio oldest_to_newest 71152 0 mage 2012-07-19 13:40:33 +0000 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). 75116 1 crogers 2012-10-02 21:24:12 +0000 (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. 75197 2 mage 2012-10-03 07:07:26 +0000 (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. 76437 3 crogers 2012-10-16 20:11:05 +0000 (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? 76471 4 mage 2012-10-17 07:13:38 +0000 (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? 76525 5 crogers 2012-10-17 21:40:39 +0000 (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. 76563 6 mage 2012-10-18 07:50:45 +0000 (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. 78323 7 crogers 2012-11-14 21:32:36 +0000 Fixed: https://dvcs.w3.org/hg/audio/rev/233781dbb864 78338 8 mage 2012-11-15 08:10:45 +0000 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. 78474 9 olivier.thereaux 2012-11-19 16:08:30 +0000 (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) 79821 10 mage 2012-12-10 11:33:00 +0000 Setting to reopened, since section 1.2. is still wrong (see https://www.w3.org/Bugs/Public/show_bug.cgi?id=18332#c8 ). 85563 11 olivier.thereaux 2013-04-04 14:37:36 +0000 (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.