GNOME.org
 

[jokosher-devel] [PATCH] doc strings api documentation

Hello everyone,

This patch adds several doc strings to several classes and methods in
Jokosher.

John

Index: CompactMixView.py
===================================================================
--- CompactMixView.py	(revision 1028)
+++ CompactMixView.py	(working copy)
@@ -19,9 +19,7 @@
 #=========================================================================
 
 class CompactMixView(gtk.Frame):
-	"""
-		This class implements the mix view
-	"""
+	""" This class implements the mix view """
 	
 	FPS = 10 # number of times a second the VUWidgets need updating
 	
@@ -29,6 +27,9 @@
 	
 	def __init__(self, project, mainview):
 		"""
+		Creates a new instance of CompactMixView
+		
+		Parameters:
 			project = the active project
 			mainview - the main Jokosher window
 		"""
@@ -57,9 +58,7 @@
 	#_____________________________________________________________________
 
 	def Update(self):
-		"""
-			Updates the mix view when requested by OnStateChanged or __init__
-		"""
+		""" Updates the mix view when requested by OnStateChanged or __init__ """
 		if self.Updating:
 			return
 		
@@ -137,28 +136,40 @@
 	#_____________________________________________________________________
 
 	def OnMinimiseTrack(self, widget, instr):
+		""" Callback for 'minimise' signal - minimises mixer strip.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			instr -- the instrument to be hidden
 		"""
-			Callback for 'minimise' signal - minimises mixer strip
-		"""
 		instr.SetVisible(False)
 		
 	#_____________________________________________________________________
 
 	def OnMaximiseTrack(self, widget, instr):
 		"""
-			Callback for 'clicked' signal on minimise buttons
-			 - maximises mixer strip
+		Callback for 'clicked' signal on minimise buttons - maximises mixer strip.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			instr -- the instrument to be shown.
+		
 		"""
 		instr.SetVisible(True)
 	#_____________________________________________________________________
 	
 	def OnStateChanged(self, obj, change=None, *extra):
 		"""
-			Called when a change of state is signalled by any of the
-			instruments that this view is 'listening' to. 
-			NOTE: the actual AddListener call is in RecordingView.py
-			as this is wher the InstrumentViewer objects are created when
-			instruments are added.
+		Called when a change of state is signalled by any of the
+		instruments that this view is 'listening' to. 
+		NOTE: the actual AddListener call is in RecordingView.py
+		as this is wher the InstrumentViewer objects are created when
+		instruments are added.
+		
+		Parameters:
+			obj -- An object to inform when this method is called.
+			change -- the change which has occured.
+			extra -- the extra parameters to be passed
 		"""
 		#don't update on volume change because it happens very often
 		if change != "volume":
@@ -167,9 +178,7 @@
 	#_____________________________________________________________________
 	
 	def OnUpdateTimeout(self):
-		""" 
-			Called at intervals (self.FPS) to update the VU meters
-		"""
+		""" Called at intervals (self.FPS) to update the VU meters """
 		if self.mainview.isPlaying:
 			self.mastermixer.vu.queue_draw()
 			
Index: AddInstrumentDialog.py
===================================================================
--- AddInstrumentDialog.py	(revision 1028)
+++ AddInstrumentDialog.py	(working copy)
@@ -20,12 +20,18 @@
 #=========================================================================
 
 class AddInstrumentDialog:
-	""" This class handles all of the processing associated with the
-		Add Instrument dialog.
-	"""	
+	""" This class handles all of the processing associated with the Add Instrument dialog. """	
 	#_____________________________________________________________________
 
 	def __init__(self, project, parent, instr=None):
+		"""
+		Creates a new instance of AddInstrumentDialog
+		
+		Parameters:
+			project -- the active project a user is working on
+			parent -- parent window of the add instrument dialog
+			instr -- the active instrument
+		"""
 		self.parent = parent
 		self.project = project
 		self.instr = instr
@@ -86,15 +92,23 @@
 	#_____________________________________________________________________
 	
 	def OnSelected(self, iconview, path):
-		"""An instrument is selected"""
+		""" Calls the OnOK method when an instrument has been selected
 		
+		Parameters:
+			iconview -- reserved for GTK callbacks, don't use it explicitly.
+			path -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		self.OnOK()
 
 	#_____________________________________________________________________
 			
 	def OnOK(self, button=None):
-		"""OK pushed on the dialog"""
+		""" This method is called when the ok button in the dialog has been clicked. It will then add the instrument selected into the main jokosher window.  
 		
+		Parameters:
+			button -- reserved for GTK callbacks, don't use it explicity.
+		"""
+		
 		sel = self.tree.get_selected_items()
 		if not self.instr:
 			for i in sel:
@@ -114,14 +128,21 @@
 	#_____________________________________________________________________
 	
 	def OnCancel(self, button):
-		"""Cancel button is pressed"""
+		""" Called when the cancel button in the dialog has been clicked
 		
+		Parameters:
+			button -- reserved for GTK callbacks, dont't use it explicity.
+		"""
 		self.dlg.destroy()
 		
 	#_____________________________________________________________________
 
 	def OnSelectionChanged(self, button):
-		"""If a new instrument icon is chosen, this method is called"""
+		""" Called when a new instrument icon is chosen. The ok button in the dialog will appear inactive if there are no instruments selected.
+		
+		Parameters:
+			button -- reserved for GTK callbacks, dont't use it explicity.
+		"""
 		sel = self.tree.get_selected_items()
 
 		if len(sel) <= 0:
@@ -132,8 +153,11 @@
 	#_____________________________________________________________________
 	
 	def OnSearchChange(self, widget):
-		"""A new letter is added to the search box, so update the search"""
+		""" This method will be called when a new letter has been added to the search box. It will then update the search results accordingly
 		
+		Parameters:
+			widget -- reserved for GTK callbacks, dont't use it explicity.
+		"""
 		search_text = self.search_entry.get_text()
 		self.model = gtk.ListStore(str, str, gtk.gdk.Pixbuf)
 		
Index: AudioPreview.py
===================================================================
--- AudioPreview.py	(revision 1028)
+++ AudioPreview.py	(working copy)
@@ -22,6 +22,7 @@
 	"""
 
 	def __init__(self):
+		""" Creates a new instance of AudioPreview """
 		gtk.ToggleButton.__init__(self, "gtk-media-play")
 		self.set_use_stock(True)
 		self.uri = None
@@ -38,13 +39,24 @@
 	#_____________________________________________________________________
 
 	def OnSelection(self, widget):
+		""" This method is called when a user selects a new file in the import audio file dialog. 
+		The preview widget then retrieves the location of the file that has been selected and sets the variable self.uri to be the location of the file it retrieves.
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+		"""
 		self.uri = widget.get_preview_uri()
 		self.set_active(False)
 		
 	#_____________________________________________________________________
 
 	def OnToggle(self, widget):
-		"Toggling the button plays or stops playing by setting ready state"
+		""" This method is called when a user toggles the preview button between a stop or playing state. 
+		This method will then set the button to appear pressed in when playing or normal when stopped. 
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, dont't use it explicitly. 
+		"""
 		if self.get_active():
 			self.previewbin.set_property("uri", self.uri)
 			self.previewbin.set_state(gst.STATE_PLAYING)
@@ -54,11 +66,22 @@
 	#_____________________________________________________________________
 			
 	def OnEOS(self, bus, message):
+		# TODO
+		"""
+	
 		self.set_active(False)
+		"""
 		
 	#_____________________________________________________________________
 
 	def OnDestroy(self, widget=None):
+		# TODO
+		""" This method destroys the active pipeline 
+		
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+		
+		"""
 		self.previewbin.set_state(gst.STATE_NULL)
 	
 	#_____________________________________________________________________
Index: AlsaDevices.py
===================================================================
--- AlsaDevices.py	(revision 1028)
+++ AlsaDevices.py	(working copy)
@@ -16,11 +16,11 @@
 #=========================================================================
 
 def GetAlsaList(type):
-	"""Returns a dictionary containing ALSA device names and their correspoding ALSA ids (e.g. hw:0).
+	""" Returns a dictionary containing ALSA device names and their correspoding ALSA ids (e.g. hw:0).
 
-	Keyword arguments:
-	type -- specifies the type of ALSA device we are looking for, playback or capture."""
-
+	Parameters:
+		type -- specifies the type of ALSA device we are looking for, playback or capture.
+	"""
 	#Get HAL Manager
 	bus = dbus.SystemBus()
 	object = bus.get_object("org.freedesktop.Hal", "/org/freedesktop/Hal/Manager")
@@ -48,9 +48,9 @@
 def GetRecordingMixers(device):
 	"""Returns a list containing all the channels which have recording switched on.
 
-	Keyword arguments:
-	device -- specifies which ALSA device (e.g. hw:0) to return values for."""
-
+	Parameters:
+		device -- specifies which ALSA device (e.g. hw:0) to return values for.
+	"""
 	recmixers = []
 	alsamixer = gst.element_factory_make('alsamixer')
 	alsamixer.set_property('device', device)
@@ -76,9 +76,12 @@
 def GetRecordingSampleRate(device="hw:0"):
 	""" 
 	   May return any of the following depending on the sound card:
-	   1) an int representing the only supported sample rate
-	   2) an IntRange class with IntRange.low and IntRange.high being the min and max sample rates
-	   3) a list of ints representing all the supported sample rates
+	   	1) an int representing the only supported sample rate
+	   	2) an IntRange class with IntRange.low and IntRange.high being the min and max sample rates
+	   	3) a list of ints representing all the supported sample rates
+	   	
+	   Parameters:
+	   	device -- return values for ALSA device "hw:0".	   
 	"""
 	
 	return GetGstElementSampleRate("alsasrc", "src", device=device)
@@ -87,16 +90,16 @@
 
 def GetGstElementSampleRate(elementName, padName, **properties):
 	""" 
-	   elementName - the name of the gstreamer element (ie "alsasrc")
-	   padName - the name of the pad to query ("src" or "sink")
-	   properties - and properties to set on the element
-	
-	   This function may return any of the following depending on the gstreamer element:
-	   1) an int representing the only supported sample rate
-	   2) an IntRange class with IntRange.low and IntRange.high being the min and max sample rates
-	   3) a list of ints representing all the supported sample rates
+	This function may return any of the following depending on the gstreamer element:
+	   	1) an int representing the only supported sample rate
+	   	2) an IntRange class with IntRange.low and IntRange.high being the min and max sample rates
+	   	3) a list of ints representing all the supported sample rates
+	   
+	Parameters:
+	   	elementName -- the name of the gstreamer element (ie "alsasrc")
+	   	padName -- the name of the pad to query ("src" or "sink")
+	   	properties -- and properties to set on the element
 	"""
-	
 	element = gst.element_factory_make(elementName)
 
 	for key, value in properties.iteritems():
@@ -120,6 +123,11 @@
 #_____________________________________________________________________
 
 def GetChannelsOffered(device):
+	""" This function will return the number of channels offered on the user's sound card.
+	
+	Parameters:
+		device -- specifies which ALSA device (e.g. hw:0) to return values for.
+	"""
 	#TODO: Quite a few assumptions here...
 	src = gst.element_factory_make('alsasrc')
 	src.set_property("device", device)
Index: InstrumentEffectsDialog.py
===================================================================
--- InstrumentEffectsDialog.py	(revision 1028)
+++ InstrumentEffectsDialog.py	(working copy)
@@ -185,11 +185,11 @@
 	#_____________________________________________________________________	
 		
 	def OnOK(self, button):
+		""" If the OK button is pressed on the dialog box, the window is destroyed.
+		
+		Parameters:
+			button -- reserved for GTK callbacks, don't use it explicitly.
 		"""
-			If the OK button is pressed on the dialog box, the window is
-			destroyed.
-		"""
-
 		self.instrument.project.RemoveListener(self)
 		self.instrument.RemoveListener(self)
 		self.window.destroy()
@@ -198,7 +198,10 @@
 	
 	def OnCancel(self, button):
 		"""
-			If the Cancel button is pressed, the dialog is destroyed.
+		If the Cancel button is pressed, the dialog is destroyed.
+			
+		Parameters:
+			button -- reserved for GTK callbacks, don't use it explicitly.
 		"""
 		self.instrument.project.RemoveListener(self)
 		self.instrument.RemoveListener(self)	
@@ -208,10 +211,13 @@
 
 	def OnTransport(self, button):
 		"""
-			Pressing the Play/Stop button on the dialog box allows the user
-			to play back the project to test if the effect settings are
-			right for them. When user press the Play button, it switches to
-			a stop button, and vice versa.
+		Pressing the Play/Stop button on the dialog box allows the user
+		to play back the project to test if the effect settings are
+		right for them. When user press the Play button, it switches to
+		a stop button, and vice versa.
+		
+		Parameters:
+			button -- reserved for GTK callbacks, don't use it explicitly.
 		"""
 		if self.isPlaying == False:
 			# things to do if the project is not already playing, and hence
@@ -225,6 +231,7 @@
 	#_____________________________________________________________________
 
 	def OnStateChanged(self,obj,change=None, *extra):
+		# TODO
 		
 		if obj is self.instrument and change == "effects":
 			self.Update()
Index: Monitored.py
===================================================================
--- Monitored.py	(revision 1028)
+++ Monitored.py	(working copy)
@@ -20,15 +20,16 @@
 	#_____________________________________________________________________
 	
 	def __init__(self):
+		""" Creates a new instance of Monitored """
 		self.listeners = []
 		
 	#_____________________________________________________________________
 		
 	def AddListener(self, obj):
-		"""Adds an object to report changes too.
+		""" Adds an object to report changes too.
 		
-		Keyword arguments:
-		obj -- An object to inform when StateChanged is called."""
+		Parameters:
+			obj -- An object to inform when StateChanged is called."""
 
 		if not obj in self.listeners:
 			self.listeners.append(obj)
@@ -36,10 +37,10 @@
 	#_____________________________________________________________________
 			
 	def RemoveListener(self, obj):
-		"""Stop reporting changes to the specified object.
+		""" Stop reporting changes to the specified object.
 		
-		Keyword arguments:
-		obj -- The object which should no longer receive change updates."""
+		Parameters:
+			obj -- The object which should no longer receive change updates."""
 
 		if obj in self.listeners:
 			self.listeners.remove(obj)
@@ -53,13 +54,12 @@
 	#_____________________________________________________________________
 	
 	def StateChanged(self, change=None, *extra):
-		"""This function should be called when we want a change to be reported to all objects previously added by AddListener. 
+		"""This method should be called when we want a change to be reported to all objects previously added by AddListener. 
 		
-		Keyword arguments:
-		change -- The change which has occured (optional).
-		extra -- Any extra parameters that should be passed (optional).
+		Parameters:
+			change -- The change which has occured (optional).
+			extra -- Any extra parameters that should be passed (optional).
 		"""
-		
 		for obj in self.listeners:
 			obj.OnStateChanged(self, change, *extra)
 			
Index: EffectWidget.py
===================================================================
--- EffectWidget.py	(revision 1028)
+++ EffectWidget.py	(working copy)
@@ -30,8 +30,12 @@
 	#_____________________________________________________________________
 	
 	def __init__(self, effect, effectname):
-		"""Constructor for the class"""
+		""" Creates a new instance of EffectWidget
 		
+		Parameters:
+			effect -- the effect to be drawn
+			effectname -- the name of the effect to be drawn
+		"""
 		gtk.DrawingArea.__init__(self)
 		self.BACKGROUND_RGB = (1, 1, 1)
 		self.TEXT_RGB = (0, 0, 0)
@@ -59,11 +63,13 @@
 	#_____________________________________________________________________
 		
 	def expose(self, widget, event):
+		""" When the widget exposes, this method is called. It then triggers
+		    a redraw
+		    
+		Parameters:
+			widget -- reserved for GTK callbacks, don't use it explicitly.
+			event -- reserved for GTK callbacks, don't use it explicitly.  
 		"""
-		   When the widget exposes, this method is called. It then triggers
-		   a redraw
-		"""
-	
 		# this is the context (the area to be drawn on) where we draw the
 		# widget
 		self.context = widget.window.cairo_create()
@@ -81,8 +87,11 @@
 	#_____________________________________________________________________
 
 	def draw(self, context):
-		"""Redraws the widget"""
-	
+		""" This method will redraw the widget the widget
+		
+		Parameters:
+			context -- a cairo drawing area
+		 """
 		# grab a reference to the drawing area
 		alloc = self.get_allocation()
 		
@@ -200,11 +209,13 @@
 	#_____________________________________________________________________
 
 	def OnMouseDown(self, widget, mouse):
+		""" If the mouse is clicked, detect where it is clicked and whether
+		    it is a double click or not.
+		   
+		Parameters:
+		   	widget -- reserved for GTK callbacks, don't use it explicitly.
+		   	mouse -- reserved for GTK callbacks, don't use it explicitly.
 		"""
-		   If the mouse is clicked, detect where it is clicked and whether
-		   it is a double click or not.
-		"""
-	
 		if self.context.in_fill(mouse.x, mouse.y):
 			self.emit("remove")
 		else:
Index: EffectPresets.py
===================================================================
--- EffectPresets.py	(revision 1028)
+++ EffectPresets.py	(working copy)
@@ -34,6 +34,7 @@
 	#_____________________________________________________________________    
 	
 	def __init__(self):
+		""" Creates a new instance of EffectsPresets """
 		Globals.EFFECT_PRESETS_VERSION = "0.2"
 		
 		# this is the main dictionary of presets
@@ -50,8 +51,14 @@
 	#_____________________________________________________________________    
 
 	def SaveSingleEffect(self, label, effectdict, effectelement, effecttype):
-		"""Write a single effect preset to a preset file"""
-	
+		""" This method will write a single effect preset to a preset file
+		
+		Parameters:
+			label --the name of the effect.
+			effectdict -- the effect dictionary.
+			effectelement -- the effect that the user selected.
+			effecttype -- the type of the effect the user selected.
+		"""
 		self.effectelement = effectelement
 		self.effecttype = effecttype
 	
@@ -88,8 +95,13 @@
 	#_____________________________________________________________________    
 
 	def SaveEffectChain(self, label, effectlist, instrumenttype):
-		"""Write an effect chain to a preset file"""        
+		"""Write an effect chain to a preset file
 		
+		Parameters:
+			label -- the name of the effect
+			effectlist -- the list of effects
+			instrumenttype -- the type of instrument currently being used
+		"""        
 		self.effectelement = None
 		self.effecttype = None
 		
@@ -143,8 +155,12 @@
 	#_____________________________________________________________________
 	
 	def LoadSingleEffectSettings(self, effectelement, presetname):
-		"""Load effect settings from a preset file for a single effect"""
-
+		""" Load effect settings from a preset file for a single effect
+		
+		Parameters:
+			effectelement -- the effect element to be loaded.
+			presetname -- the name of the preset to be loaded.
+		"""
 		presetfile = Globals.EFFECT_PRESETS_PATH + "/" + presetname + ".jpreset"
 		Globals.debug(presetfile)
 
@@ -162,18 +178,23 @@
 	#_____________________________________________________________________    
 	
 	def LoadSingleEffectList(self):
+		# TODO
 		pass
 		
 	#_____________________________________________________________________    
 	
 	def LoadInstrumentEffectList(self):
+		# TODO
 		pass
 		
 	#_____________________________________________________________________    
 	
 	def LoadInstrumentEffectChain(self, presetname):
-		"""Load settings from the preset file for an effects chain"""
+		""" Load settings from the preset file for an effects chain
 		
+		Parameters:
+			presetname -- the name of the preset to be loaded.
+		 """
 		presetfile = Globals.EFFECT_PRESETS_PATH + "/" + presetname + ".jpreset"
 			
 		if not os.path.exists(presetfile):
@@ -198,7 +219,7 @@
 	#_____________________________________________________________________
 	
 	def FillEffectsPresetsRegistry(self):
-		"""Read in all presets into the main presets registry"""
+		""" Read in all presets into the main presets registry """
 		
 		Globals.debug("Reading in presets...")
 		presetsfiles = glob.glob(Globals.EFFECT_PRESETS_PATH + "/*.jpreset")
@@ -253,8 +274,8 @@
 	#_____________________________________________________________________
 	
 	def FillLADSPARegistry(self):
-		"""Fill Globals.LADSPA_FACTORY_REGISTRY with effects on the system. This
-		is to ensure only presets with effects on the current system are listed."""
+		""" Fill Globals.LADSPA_FACTORY_REGISTRY with effects on the system. This
+		is to ensure only presets with effects on the current system are listed. """
 
 
 		Globals.debug("Filling LADSPA Registry")
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]