# Documenting API Input/Output Examples

## TL;DR

This paper presents a prototype toolset that automatically generates dynamic I/O examples for APIs by logging actual function executions and embedding these examples into documentation, enhancing understanding for users.

## Contribution

The paper introduces a novel toolset that captures real I/O examples during API testing and integrates them into documentation, addressing a gap in current static documentation tools.

## Key findings

- Generated 400 I/O examples for three C libraries
- Successfully integrated I/O examples into API documentation
- Demonstrated the toolset's effectiveness in real-world libraries

## Abstract

When learning to use an Application Programming Interface (API), programmers need to understand the inputs and outputs (I/O) of the API functions. Current documentation tools automatically document the static information of I/O, such as parameter types and names. What is missing from these tools is dynamic information, such as I/O examples---actual valid values of inputs that produce certain outputs. In this paper, we demonstrate a prototype toolset we built to generate I/O examples. Our tool logs I/O values when API functions are executed, for example in running test suites. Then, the tool puts I/O values into API documents as I/O examples. Our tool has three programs: 1) funcWatch, which collects I/O values when API developers run test suites, 2) ioSelect, which selects one I/O example from a set of I/O values, and 3) ioPresent, which embeds the I/O examples into documents. In a preliminary evaluation, we used our tool to generate four hundred I/O examples for three C libraries: ffmpeg, libssh, and protobuf-c.