Name
Abstract | ||
|---|---|---|
The rise of component-based software development has created an urgent need for effective application program interface (API) documentation. Experience has shown that it is hard to create precise and readable documentation. Prose documentation can provide a good overview but lacks precision. Formal methods offer precision but the resulting documentation is expensive to develop. Worse, few developers have the skill or inclination to read formal documentation.We present a pragmatic solution to the problem of API documentation. We augment the prose documentation with executable test cases, including expected outputs, and use the prose plus the test cases as the documentation. With appropriate tool support, the test cases are easy to develop and read. Such test cases constitute a completely formal, albeit partial, specification of input/output behavior. Equally important, consistency between code and documentation is demonstrated by runnig the test cases. This approach provides an attractive bridge between formal and informal documentation. We also present a tool that supports compact and readable test cases, and generation of test drivers and documentation, and illustrate the approach with detailed case studies. |
Year | DOI | Venue |
|---|---|---|
2003 | 10.1016/S0164-1212(02)00055-9 | Journal of Systems and Software |
Keywords | Field | DocType |
executable test case,resulting documentation,formal documentation,executable example,readable test case,readable documentation,informal documentation,prose documentation,test driver,api documentation,test case,testing,application programming interfaces,formal methods,api,input output,component based software development,formal method,formal specification,application program interface | Programming language,Systems engineering,Software engineering,Computer science,Software documentation,Technical documentation,Common Source Data Base,Internal documentation,Formal specification,Test case,Application programming interface,Documentation | Journal |
Volume | Issue | ISSN |
66 | 2 | The Journal of Systems & Software |
Citations | PageRank | References |
5 | 0.45 | 29 |
Authors | ||
2 | ||
Name | Order | Citations | PageRank |
|---|---|---|---|
| Daniel Hoffman | 1 | 309 | 26.89 |
| Paul Strooper | 2 | 701 | 68.70 |