Documenting APIs?

[David Farning]

I am starting to document the APIs for smart's interface code.  Do any
of the developers have preferrences or experience documenting python
code?


Below is a table of public method of Progress, TextProgress, and
GTKProgress.

Progress                TextProgress            GtkProgress
__init()                __init__()             __init__(hassub)

                        setFetcher(fetcher)
                                                setFetcherMode(flag)
lock()
unlock()
                        tick()
start()                 start()
stop()                  stop()                  stop()
setHasSub(flag)
getHasSub(flag)
getSubCount()
show()
expose()                expose(...)             expose(...)
setTopic(topic)
get()
set(current,total, data={})
add(value)
addTotal(value)
setSubTopic(subkey, subtopic)
getSub(subkey)
getSubData(subkey, _none=[None])
setSub(...)
addSub(subkey, value)
addSubTotal(subkey, value)
setDone
setSubDone(subkey)
setStopped()
setSubStopped(subkey)
resetSub(subkey)


1.  I am looking at is splitting show and expose up into show/showSub
and expose/subExpose.

2.  Change the constructors to make them consistent.
__init__(hassub=False, topic="", progress=()) looks about the cleanest.

3. Currently, lock/unlock are define but never used.
	s/self.__lock.acquire()/self.lock
	s/self.__lock.release()/self.unlock

4. Rename get/set to getProgress/setProgress. 

Others?

Dave