Documenting APIs?

[Keith Roberts]

Hi David. I was wondering what method you are using to 
create the documentation. Are you using some type of 
document generator, or are you doing it all by hand?

Regards

Keith

------------------------------------------------------------
http://www.karsites.net
http://www.raised-from-the-dead.org.uk

This email address is challenge-response protected with 
http://www.tmda.net
------------------------------------------------------------

On Fri, 27 Oct 2006, David Farning wrote:

> To: smart at labix.org
> From: David Farning <dfarning at gmail.com>
> Subject: Documenting APIs?
> 
> 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
> 
>