Hi everybody, I have been playing around with a new system for documenting VIFF. It is called Sphinx and has been developed for documenting Python itself:
http://sphinx.pocoo.org/ http://docs.python.org/dev/ It uses ReST like the current system we have for the webpages, but it offers much better ways to integrate the code into the documentation. Sphinx also encourages writing documentation for *humans* and not just for machines. With that I mean the stupid tendency one has to write stuff like (in viff.shamir): def share(secret, threshold, num_players): """Shamir share secret. @param secret: the secret to be shared. @type secret: a field element @param threshold: maximum number of shares that reveal nothing about the secret. @type threshold: integer @param num_players: number of players. @type num_players: integer @return: shares, one for each player. @returntype: C{list} of (player id, share) pairs """ when this would have been enough: def share(secret, threshold, num_players): """Shamir share secret. The *threshold* indicates the maximum number of shares that reveal nothing about *secret*. The return value is a list of ``(player id, share)`` pairs. """ The second version is more informal, but I find it much better this is corresponds better to the way I think and so I don't have to parse what I read twice. And the doctest examples make it very clear how this function works anyway. I think we should still keep the epydoc generated API documentation around since it offers some nice class inheritance diagrams and some people might prefer its more rigid appearance. Epydoc understands ReST too, so this should work out nicely. As I said I have already begun the conversion and Mikkel has joined me as well. You can see the results here for now: http://www.daimi.au.dk/~mg/viff/index.html The documentation on program counters is new: http://www.daimi.au.dk/~mg/viff/program-counters.html When VIFF 0.5 is out we can merge this back into the main repository and begin writing lots of good documentation for VIFF 0.6! -- Martin Geisler _______________________________________________ viff-devel mailing list (http://viff.dk/) [email protected] http://lists.viff.dk/listinfo.cgi/viff-devel-viff.dk
