From: daid Date: Fri, 14 Feb 2014 17:17:14 +0000 (+0100) Subject: Add some more documentation. X-Git-Tag: 14.02-RC2~11 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=54d22bb91db9eacd47763aeaa6c3c3a8f250929d;p=cura.git Add some more documentation. --- diff --git a/Cura/avr_isp/intelHex.py b/Cura/avr_isp/intelHex.py index 91422ad5..fb78bb0a 100644 --- a/Cura/avr_isp/intelHex.py +++ b/Cura/avr_isp/intelHex.py @@ -7,6 +7,9 @@ __copyright__ = "Copyright (C) 2013 David Braam - Released under terms of the AG import io def readHex(filename): + """ + Read an verify an intel hex file. Return the data as an list of bytes. + """ data = [] extraAddr = 0 f = io.open(filename, "r") @@ -38,4 +41,4 @@ def readHex(filename): else: print(recType, recLen, addr, checkSum, line) f.close() - return data \ No newline at end of file + return data diff --git a/Cura/avr_isp/stk500v2.py b/Cura/avr_isp/stk500v2.py index 975dd30b..e64e1548 100644 --- a/Cura/avr_isp/stk500v2.py +++ b/Cura/avr_isp/stk500v2.py @@ -165,12 +165,14 @@ def portList(): return ret def runProgrammer(port, filename): + """ Run an STK500v2 program on serial port 'port' and write 'filename' into flash. """ programmer = Stk500v2() programmer.connect(port = port) programmer.programChip(intelHex.readHex(filename)) programmer.close() def main(): + """ Entry point to call the stk500v2 programmer from the commandline. """ import threading if sys.argv[1] == 'AUTO': print portList() diff --git a/Cura/cura.py b/Cura/cura.py index e43c9123..32b82158 100644 --- a/Cura/cura.py +++ b/Cura/cura.py @@ -13,6 +13,9 @@ from optparse import OptionParser from Cura.util import profile def main(): + """ + Main Cura entry point. Parses arguments, and starts GUI or slicing process depending on the arguments. + """ parser = OptionParser(usage="usage: %prog [options] .stl") parser.add_option("-i", "--ini", action="store", type="string", dest="profileini", help="Load settings from a profile ini file") diff --git a/Cura/doctest.py b/Cura/doctest.py index b22dd10c..a96f2626 100644 --- a/Cura/doctest.py +++ b/Cura/doctest.py @@ -1,6 +1,6 @@ """ A helper file to check which parts of the code have documentation and which are lacking documentation. -This because much of the Cura code is currently undocumented which needs to be improved.' +This because much of the Cura code is currently undocumented which needs to be improved. """ import os import traceback @@ -46,6 +46,8 @@ def main(): moduleDocCount = 0 functionCount = 0 functionDocCount = 0 + memberCount = 0 + memberDocCount = 0 typeCount = 0 typeDocCount = 0 undocList = [] @@ -65,8 +67,8 @@ def main(): functionCount += 1 if inspect.getdoc(a): functionDocCount += 1 - # else: - # undocList.append('%s.%s' % (module.__name__, name)) + else: + undocList.append('%s.%s' % (module.__name__, name)) elif type(a) is types.TypeType: typeCount += 1 if inspect.getdoc(a): @@ -78,16 +80,17 @@ def main(): if type(a2) is types.MethodType: if hasattr(a.__bases__[0], name2): continue - functionCount += 1 + memberCount += 1 if inspect.getdoc(a2): - functionDocCount += 1 + memberDocCount += 1 # else: # undocList.append('%s.%s.%s' % (module.__name__, name, name2)) print '%d/%d modules have documentation.' % (moduleDocCount, len(moduleList)) - print '%d/%d functions have documentation.' % (functionDocCount, functionCount) print '%d/%d types have documentation.' % (typeDocCount, typeCount) - print '%.1f%% documented.' % (float(moduleDocCount + functionDocCount + typeDocCount) / float(len(moduleList) + functionCount + typeCount) * 100.0) + print '%d/%d functions have documentation.' % (functionDocCount, functionCount) + print '%d/%d member functions have documentation.' % (memberDocCount, memberCount) + print '%.1f%% documented.' % (float(moduleDocCount + functionDocCount + typeDocCount + memberDocCount) / float(len(moduleList) + functionCount + typeCount + memberCount) * 100.0) print '' print 'You might want to document:' for n in xrange(0, 10): diff --git a/Cura/util/profile.py b/Cura/util/profile.py index f563d6dc..16dda8cd 100644 --- a/Cura/util/profile.py +++ b/Cura/util/profile.py @@ -472,6 +472,9 @@ def getSettingsForCategory(category, subCategory = None): ## Profile functions def getBasePath(): + """ + :return: The path in which the current configuration files are stored. This depends on the used OS. + """ if platform.system() == "Windows": basePath = os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..")) #If we have a frozen python install, we need to step out of the library.zip @@ -484,6 +487,9 @@ def getBasePath(): return basePath def getAlternativeBasePaths(): + """ + Search for alternative installations of Cura and their preference files. Used to load configuration from older versions of Cura. + """ paths = [] basePath = os.path.normpath(os.path.join(getBasePath(), '..')) for subPath in os.listdir(basePath): @@ -496,11 +502,18 @@ def getAlternativeBasePaths(): return paths def getDefaultProfilePath(): + """ + :return: The default path where the currently used profile is stored and loaded on open and close of Cura. + """ return os.path.join(getBasePath(), 'current_profile.ini') def loadProfile(filename, allMachines = False): + """ + Read a profile file as active profile settings. + :param filename: The ini filename to save the profile in. + :param allMachines: When False only the current active profile is saved. If True all profiles for all machines are saved. + """ global settingsList - #Read a configuration file as global config profileParser = ConfigParser.ConfigParser() try: profileParser.read(filename) @@ -529,8 +542,12 @@ def loadProfile(filename, allMachines = False): set.setValue(unicode(profileParser.get(section, set.getName()), 'utf-8', 'replace')) def saveProfile(filename, allMachines = False): + """ + Save the current profile to an ini file. + :param filename: The ini filename to save the profile in. + :param allMachines: When False only the current active profile is saved. If True all profiles for all machines are saved. + """ global settingsList - #Save the current profile to an ini file profileParser = ConfigParser.ConfigParser() if allMachines: for set in settingsList: @@ -558,7 +575,7 @@ def saveProfile(filename, allMachines = False): profileParser.write(open(filename, 'w')) def resetProfile(): - #Read a configuration file as global config + """ Reset the profile for the current machine to default. """ global settingsList for set in settingsList: if not set.isProfile(): @@ -577,6 +594,10 @@ def resetProfile(): putProfileSetting('retraction_enable', 'True') def setProfileFromString(options): + """ + Parse an encoded string which has all the profile settings stored inside of it. + Used in combination with getProfileString to ease sharing of profiles. + """ options = base64.b64decode(options) options = zlib.decompress(options) (profileOpts, alt) = options.split('\f', 1) @@ -595,6 +616,10 @@ def setProfileFromString(options): settingsDictionary[key].setValue(value) def getProfileString(): + """ + Get an encoded string which contains all profile settings. + Used in combination with setProfileFromString to share settings in files, forums or other text based ways. + """ p = [] alt = [] global settingsList @@ -620,6 +645,9 @@ def insertNewlines(string, every=64): #This should be moved to a better place th return '\n'.join(lines) def getPreferencesString(): + """ + :return: An encoded string which contains all the current preferences. + """ p = [] global settingsList for set in settingsList: @@ -631,6 +659,11 @@ def getPreferencesString(): def getProfileSetting(name): + """ + Get the value of an profile setting. + :param name: Name of the setting to retrieve. + :return: Value of the current setting. + """ if name in tempOverride: return tempOverride[name] global settingsDictionary @@ -648,12 +681,13 @@ def getProfileSettingFloat(name): return 0.0 def putProfileSetting(name, value): - #Check if we have a configuration file loaded, else load the default. + """ Store a certain value in a profile setting. """ global settingsDictionary if name in settingsDictionary and settingsDictionary[name].isProfile(): settingsDictionary[name].setValue(value) def isProfileSetting(name): + """ Check if a certain key name is actually a profile value. """ global settingsDictionary if name in settingsDictionary and settingsDictionary[name].isProfile(): return True @@ -661,9 +695,15 @@ def isProfileSetting(name): ## Preferences functions def getPreferencePath(): + """ + :return: The full path of the preference ini file. + """ return os.path.join(getBasePath(), 'preferences.ini') def getPreferenceFloat(name): + """ + Get the float value of a preference, returns 0.0 if the preference is not a invalid float + """ try: setting = getPreference(name).replace(',', '.') return float(eval(setting, {}, {})) @@ -671,12 +711,17 @@ def getPreferenceFloat(name): return 0.0 def getPreferenceColour(name): + """ + Get a preference setting value as a color array. The color is stored as #RRGGBB hex string in the setting. + """ colorString = getPreference(name) return [float(int(colorString[1:3], 16)) / 255, float(int(colorString[3:5], 16)) / 255, float(int(colorString[5:7], 16)) / 255, 1.0] def loadPreferences(filename): + """ + Read a configuration file as global config + """ global settingsList - #Read a configuration file as global config profileParser = ConfigParser.ConfigParser() try: profileParser.read(filename)