From 855e4731836b4d77c0aa3a888759828f168d030f Mon Sep 17 00:00:00 2001
From: Ryan Rix <phrkonaleash@gmail.com>
Date: Sat, 5 Dec 2009 00:45:33 -0700
Subject: Finished code documentation, added some good TODO entries.

---
 backend/tour_menuobject.py | 100 +++++++++++++++++++++++++++++++--------------
 1 file changed, 69 insertions(+), 31 deletions(-)

(limited to 'backend')

diff --git a/backend/tour_menuobject.py b/backend/tour_menuobject.py
index ddfa14e..c97c9ec 100644
--- a/backend/tour_menuobject.py
+++ b/backend/tour_menuobject.py
@@ -23,9 +23,9 @@ import xml.parsers.expat
 import sys
 
 
-'''
+"""
 This will be expanded
-'''
+"""
 class MenuNode:
 	parent = False
 	nodes = list()
@@ -34,12 +34,27 @@ class MenuNode:
 	def __init__(self, nodeType):
 		self.nodeType = nodeType
 
-'''
+"""
 Each one of these objects represents one section of Fedora-tour and all of the content 
 which exists below it. The frontend should keep these in a list, ordered by MenuObject.Priority
 
-What this sort of does is create a lazy DOM of menuNode objects
-'''
+What this sort of does is create a lazy DOM of menuNode objects where each menuNode has a list of
+children and a single parent, linked directly to the object, to create a virtual layout of the XML.
+
+node.nodeType = package
+	nodes: page 1
+	nodes: page 2
+	parent: 0
+
+node.nodeType = Page
+	parent: Package
+	content and stuff
+
+node.nodeType = Page
+	parent: Package
+	content and stuff
+
+"""
 class MenuObject:
 	isValid = True
 	currenElement = False
@@ -79,10 +94,10 @@ class MenuObject:
 		
 		self.parser.ParseFile(open(package,"r"))
 		
-		'''
+		"""
 		The contents of IconID specify only the short name of an icon, not the full path; this
 		function finds the full path of an icon and stores it in self.Icon
-		'''
+		"""
 		self.Icon = self.makeIcon(self.IconID)
 	
 	def addNode(self,parent,nodeType):
@@ -94,6 +109,46 @@ class MenuObject:
 		
 		return node
 	
+	"""
+	This function parses the opening tags in the XML file and sets the proper value in 
+	self.currentElement for the parserCharData method to handle properly. This will probably
+	a little bit more intuitively in the future, but for now it works.
+	"""
+	def parserStartElement(self, name, attrs):
+		print "Encountered "+name+" node Start"
+		
+		self.currentElement = name
+		
+		if name == "Package":
+			"""
+			This is always assumed to be the root node.
+			"""
+			self.rootNode = self.addNode(False,"Package")
+			self.activeNode = self.rootNode
+		
+		elif name == "Page":
+			"""
+			The Page entities are new nodes
+			"""
+			self.activeNode = self.addNode(self.activeNode, "Page")
+						
+		elif name == "Icon" or name == "DocRoot" or name == "Locale" or name == "Priority":
+			""" 
+			These tags are only allowed under root, so we should err if this happens.
+			"""
+			if self.activeNode.parent != False:
+				print "<"+name+"> node is only allowed underneath the <Package> Node. Please file a bug on the Fedora-tour Fedora component at http://bugzilla.redhat.com"
+				sys.exit()
+	
+	"""
+	I'm about 99% sure that this code could be written in a cleaner fashion and not
+	so damn ugly, but here it is, assigning variables in the object. At some point,
+	I'll look at moving these to attrs of the Page and Package entities, just so that
+	the code could be a little bit cleaner. I know for sure that DisplayName could be
+	in both and that Icon, DocRoot, Locale, and Priority could easily end up under Package.
+	TODO: Rewrite this to be cleaner.
+	TODO: Finish handlers for other entities, you missed a few.
+	"""
 	def parserCharData(self, data):
 		if self.currenElement == False:
 			pass
@@ -112,32 +167,12 @@ class MenuObject:
 		
 		elif self.currentElement == "Priority":
 			self.Priority = data
-			
-	def parserStartElement(self, name, attrs):
-		print "Encountered "+name+" node Start"
-		
-		self.currentElement = name
-		
-		if name == "Package":
-			self.rootNode = self.addNode(False,"Package")
-			self.activeNode = self.rootNode
-		
-		elif name == "Page":
-			self.activeNode = self.addNode(self.activeNode, "Page")
 		
-		elif name == "DisplayName":
-			self.currentElement = "DisplayName"
-		
-		elif name == "Icon" or name == "DocRoot" or name == "Locale" or name == "Priority":
-			""" 
-			These tags are only allowed under root, so we should err if this happens.
-			"""
-			if self.activeNode.parent != False:
-				print self.rootNode
-				print self.activeNode
-				print "<"+name+"> node is only allowed underneath the <Package> Node. Please file a bug on the Fedora-tour Fedora component at http://bugzilla.redhat.com"
-				sys.exit()
 		
+	"""
+	This just checks if a Page element is closing, since that will step us down one
+	level in the "DOM" tree
+	"""
 	def parserEndElement(self, name):
 		print "Encountered "+name+" node End"
 		
@@ -146,6 +181,9 @@ class MenuObject:
 		if name == "Page":
 			self.activeNode = self.activeNode.parent
 	
+	"""
+	TODO
+	"""
 	def makeIcon(self, iconID):
 		pass
 		
-- 
cgit