[Twisted-Python] API docs - and examples

[Mukhsein Johari]

On Friday 19 July 2002 13:17, Christopher Armstrong wrote:
> I was talking to MetaCosm, and he said the template for API docs he uses
> in his professional projects is like so:
>
> """
> Usage:
>    foo() -> baz
>
> Examples:
>    if blah(): foo()
>
> Big Picture: (!!)
>    This class is meant to be used in a Quuxer, and you should usually
> override the getBaz method to return a Spam instance, although it's not
> required.
>
> NOTES:
>   This class is currently in a state of flux; it will soon be
> refactored, so watch out for API changes
>
> """
>
> etc.
>
> The main thing here is "Big Picture", which should give the method/class
> some context. NOTES is mainly for temporary stuff; It's probably not
> crucial to be in the docstrings (probably it should just be in near-by
> #XXX comments). So yeah, I urge people who are writing docstrings to put
> stuff into context; I'll try to do the same thing. Whether or not you
> use a similar format isn't really important, but it seems sane enough to
> me. We'll probably be doing a lot of this during the 0.99.0 cycle, but
> it's never too early to start improving documentation :)
>

Yes, I fully agree here! Without the big picture it is difficult to determine 
the contexts of all modules and classes - especially for newbie "twistas". 
Also, we need some contextual examples in the api docs itself. A full blown 
example should be (and generally is)  found in doc/examples.

Speaking of examples, could the author of the examples please add comments and 
some explanations of the examples? I'm sure it's all quite obvious to the 
author but for newbies, it's a bit too terse. Especially when your head is 
till spinning with banana spreads and the like. Jelly? What _is_ twistd? 
Should there be only one twistd running with multiple "protocol handlers" or 
one twistd running per protocol?

With some of the examples, I find myself saying: "What? That's it? It can't be 
that simple! Am I missing something?" Some explanations in the code 
(comments) would go a long way to solving this.

Doc problems:
---------------
Some of the newer documentation is quite good in the sense that it hints at a 
lot but its a bit confusing. The stuff about web-widgets and dom 
templates...It's starts out really great but ends before it should! :-)

The widgets.html doc for example. It says that the code in the Example.tar.gz 
explains why you get "No Resource" error when you first start it up. Erm...I 
looked at the code and no where does it say why. And what to do afterwards. I 
still don't understand how web-widgets work! Where do you then point the 
browser?

Also, what's a reactor? Is there some other doc to explain the concept of 
reactors? Would you use defereds in a web application? When and why?

As you can see, there are problems with the docs. I understand the main 
twistas are too busy (insane is more appropriate!) with twisted itself, to 
write more docs. Honestly, I would _love_ to write some docs, tutorials and 
howtos, if only I could understand the thing myself!

-- 
Regards,
Mukhsein Johari