Back to search

University of York

A Methodology for Intentional Specification and User-Centered Documentation of Object-Oriented APIs

Abstract

dc:description.abstract

The ideal companion to any application programming interface (API) is its documentation, which can take various forms, such as API reference documentation, user guides, and tutorials. One of the essential resources for learning APIs, commonly found in many types of API documentation, is code examples that demonstrate common API usage. However, writing and maintaining effective API usage examples is often a demanding and repetitive process for API developers. This is because API users ideally expect these examples to be simple, standalone, and linear. This PhD research addresses this challenge by providing an approach to assist API developers in producing and maintaining effective API usage examples. The approach also aims to support the development of code examples that align with API users' expectations, thereby promoting API learnability. Additionally, this research proposes a method to assess coverage of API code examples. The proposed approach provides API developers with a dedicated API description language that enables them to concisely describe intended APIs. This API description is then utilised to report code example coverage both textually and visually. The evaluation conducted in this research demonstrates that the proposed techniques can reduce the effort required to write and maintain API code examples by minimising repetition in example code and generating linear code. A controlled user study further shows that linear code examples are easier to comprehend and are preferred by API users. The findings also indicate that the proposed code example coverage tool and its accompanying API description language can simplify the process of describing intended APIs for API developers by providing features that facilitate formal and concise API specifications.

Degree

thesis:*
Name dc:type.qualificationname
Ph.D
Level dc:type.qualificationlevel
doctoral
Grantor dc:publisher.institution
University of York
Year dc:date.issued
2025

Author and committee

dc:creator, dc:contributor.*
Author dc:creator
  • Alharbi, Seham Abdulrahman A
Advisor dc:contributor.advisor
  • Kolovos, Dimitris
ORCID person:identifier.orcid

Rights

Language dc:language.dcterms_iso639_2
eng

Chain of custody

source
Harvested from
White Rose University Consortium
Base URL
etheses.whiterose.ac.uk/cgi/oai2
Last updated
2026-11-18
Source record
OAI-PMH GetRecord
related terms
citation

Alharbi, Seham Abdulrahman A. A Methodology for Intentional Specification and User-Centered Documentation of Object-Oriented APIs. doctoral thesis, University of York, 2025.