Automatic API generation assumptions
====================================

This document tries to document what assumptions/needs are essential
for automatical generation of API based on unittests.

XXX This document overlaps a little bit with api-docs.txt, but still
a purpose is slightly different.

* We use debugger hook to trace certain function calls/returns. Basically
  we install global tracing function at point where we call test and we
  catch all the calls to functions which are needed by us.

* API is explicitely fixed (the formats of input should differ, ie. pylib
  uses py.__pkg__, while pypy would have some explicit text files/source files
  which define API of certain functionallity)

* Unittests used for doc generation are fixed per API (for pylib it's very
  easy - we just specify directory, or collect all the data which py.test
  gathers).

* We have to agree on some format for __doc__ specification. ReST seems
  obvious for ReST backend, while different backends might reinterpret it
  or even leave it as is.

* The events about seen stuff (like FunctionCall(args)) goes to flexible
  enough object to support possibly any backend.

* We can use pypy annotation type system to track most-general type
  of call, or better steal it as much as possible and define some
  on our own. (Like usually it's better to track interface for some
  object which was really used, than least basic superclass of arguments
  that went inside).

Milestone 1:
------------

Date is set till sprint in Duesseldorf.