Browse Prior Art Database

Incorporating Handwritten Examples Into Generated API Documentation Disclosure Number: IPCOM000240956D
Publication Date: 2015-Mar-13
Document File: 5 page(s) / 98K

Publishing Venue

The Prior Art Database


Disclosed is a tool that enables information developers to incorporate handwritten examples into generated Application Program Interface (API) documentation.

This text was extracted from a PDF file.
This is the abbreviated version, containing approximately 41% of the total text.

Page 01 of 5

Incorporating Handwritten Examples Into Generated API Documentation

Application Program Interface (API) documentation may not be user-friendly or helpful, because it contains only information retrieved from source code with no examples. Without examples, readers often use trial and error to find working commands. In many cases, examples cannot be added to source code to be retrieved from API documentation generation tools, and even this were possible, information developers rarely have the time or technical skill to write examples into the source code. In addition, information developers cannot add information to the API documentation output after generation, because that information is overwritten by the next generation process. As a result, information developers may put examples of API commands and clarifying information about those commands in separate documentation, which significantly reduces the usefulness of the documentation by fragmenting the information.

The method disclosed herein enables information developers to provide examples for

API documentation using a tool for incorporating developer written examples into generated API documentation.

The tool uniquely identifies API commands using the structure of the API. Then, information developers write command examples in separate documentation files, tagging that information with matching unique identification. The API generation tool merges information from these two sources to create a single set of documentation that contains both generated source-code information and handwritten examples from information developers. The examples are used again, instead of being overwritten by the generation process, responsive to documentation regeneration for a new version.

The method and system is compatible with typical annotation-based API documentation, such as Representational State Transfer with Java* (JAX-RS) annotations. These annotations provide information about commands in the same place in the source code that implements the commands. The annotated Java code depicted in Figure 1 shows a command that has five parameters, each with an annotation named @Description that provides documentation for the parameter. The command itself includes a @Summary annotation that provides information about the command. These annotations are typical for API documentation.

Figure 1: Annotated Java code


Page 02 of 5

The @Path annotation describes the relative location of the command in the API tree of resources. This information provides a way for the method to identify this command and associate it with examples.

For the examples, the method uses one or more Darwin Information Typing

Architecture (DITA) files as an information source. These files are typical source files for documentation; many information developers are more familiar with this format than source-code formats. However, many source file formats for the examples may be used.

DITA code depicted in Figure 2 shows two example...