Add some more documentation.

diff --git a/Cura/avr_isp/intelHex.py b/Cura/avr_isp/intelHex.py
index 91422ad582a6a2a6d2db0d9e06f69c4bd8d03988..fb78bb0ac587132597a784929b962b8cdc4a8047 100644 (file)
--- 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 975dd30b933d8d89630bdd9dbe8ac078dd39afff..e64e15486e0dc33c371cae805e46903b9edb57b8 100644 (file)
--- 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 e43c91239af2a8ebfd6f9f77670d97a6139ee3b6..32b82158dc588bc825d98f2ea7ccf0311a90f1a3 100644 (file)
--- 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] <filename>.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 b22dd10cafb22d9e1098da151744eb811c0856c8..a96f26263f17e7e16beb7793ba430d75dd37f65d 100644 (file)
--- 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 f563d6dc0aff638311793d904a62b4b024d09318..16dda8cd118d41338c7ff34ea54ea5feb8324491 100644 (file)
--- 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)