41 lines
1.5 KiB
Plaintext
41 lines
1.5 KiB
Plaintext
|
|
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.
|
|
|