Towards Usable API Documentation

Khan, Junaed Younus

Towards Usable API Documentation

dc.contributor.advisor	Uddin, Gias
dc.contributor.author	Khan, Junaed Younus
dc.contributor.committeemember	Barcomb, Ann
dc.contributor.committeemember	Walker, Robert James
dc.date	2023-11
dc.date.accessioned	2023-07-17T17:26:28Z
dc.date.available	2023-07-17T17:26:28Z
dc.date.issued	2023-07
dc.description.abstract	The learning and usage of an API is supported by documentation. Like source code, API documentation is itself a software product. Several research results show that bad design in API documentation can make the reuse of API features difficult. Indeed, similar to code smells, poorly designed API documentation can also exhibit 'smells'. Such documentation smells can be described as bad documentation styles that do not necessarily produce incorrect documentation but make the documentation difficult to understand and use. This thesis aims to enhance API documentation usability by addressing such documentation smells in three phases. In the first phase, we developed a catalog of five API documentation smells consulting literature on API documentation issues and online developer discussion. We validated their presence in the real world by creating a benchmark of 1K official Java API documentation units and conducting a survey of 21 developers. The developers confirmed that these smells hinder their productivity and called for automatic detection and fixing. In the second phase, we developed machine-learning models to detect the smells using the 1K benchmark, however, they performed poorly when evaluated on larger and more diverse documentation sources. We explored more advanced models; employed re-training and hyperparameter tuning to further improve the performance. Our best-performing model, RoBERTa, achieved F1-scores of 0.71-0.93 in detecting different smells. In the third phase, we first focused on evaluating the feasibility and impact of fixing various smells in the eyes of practitioners. Through a second survey of 30 practitioners, we found that fixing the lazy smell was perceived as the most feasible and impactful. However, there was no universal consensus on whether and how other smells can/should be fixed. Finally, we proposed a two-stage pipeline for fixing lazy documentation, involving additional textual description and documentation-specific code example generation. Our approach utilized a large language model, GPT- 3, to generate enhanced documentation based on non-lazy examples and to produce code examples. The generated code examples were refined iteratively until they were error-free. Our technique demonstrated a high success rate with a significant number of lazy documentation instances being fixed and error-free code examples being generated.
dc.identifier.citation	Khan, J. Y. (2023). Towards usable API documentation (Master's thesis, University of Calgary, Calgary, Canada). Retrieved from https://prism.ucalgary.ca.
dc.identifier.uri	https://hdl.handle.net/1880/116743
dc.identifier.uri	https://dx.doi.org/10.11575/PRISM/41585
dc.language.iso	en
dc.publisher.faculty	Schulich School of Engineering
dc.publisher.institution	University of Calgary
dc.rights	University of Calgary graduate students retain copyright ownership and moral rights for their thesis. You may use this material in any way that is permitted by the Copyright Act or through licensing that has been assigned to the document. For uses that are not allowable under copyright legislation or licensing, you are required to seek permission.
dc.subject	software engineering
dc.subject	API documentation
dc.subject	documentation usability
dc.subject	documentation smell
dc.subject	empirical study
dc.subject	machine learning
dc.subject	natural language processing
dc.subject	large language model
dc.subject	automatic detection
dc.subject	automatic fixing
dc.subject.classification	Computer Science
dc.subject.classification	Artificial Intelligence
dc.subject.classification	Engineering--System Science
dc.title	Towards Usable API Documentation
dc.type	master thesis
thesis.degree.discipline	Engineering – Electrical & Computer
thesis.degree.grantor	University of Calgary
thesis.degree.name	Master of Science (MSc)
ucalgary.thesis.accesssetbystudent	I do not require a thesis withhold – my thesis will have open access and can be viewed and downloaded publicly as soon as possible.