# Automatic Detection of Five API Documentation Smells: Practitioners' Perspectives

**Authors:** Junaed Younus Khan, Md. Tawkat Islam Khondaker, Gias Uddin, Anindya Iqbal  
**arXiv:** [2102.08486](https://arxiv.org/abs/2102.08486)  
**Date:** 2021-02-16  
**Summary page:** https://www.summarizepaper.com/en/arxiv-id/2102.08486v1/

## Key points

- API documentation plays a crucial role in learning and utilizing an API, similar to source code
- Poorly designed documentation can hinder the ease of reusing API features
- 'Smells' in API documentation are indicators of bad documentation styles that impede understanding and usability
- The research by Khan et al. identifies five distinct types of API documentation smells
- A survey with 21 professional software developers confirmed the prevalence of these smells in existing API documentation and their negative impact on productivity
- The authors developed tools using rule-based techniques and deep learning classifiers to automatically detect and rectify these issues
- Their best-performing classifier, BERT, achieved impressive F1-scores ranging from 0.75 to 0.97
- This study addresses the lack of prior research on automatically detecting API documentation smells and aims to enhance developer experiences for more efficient software development practices

## Summary

In their paper titled "Automatic Detection of Five API Documentation Smells: Practitioners' Perspectives," authors Junaed Younus Khan, Md. Tawkat Islam Khondaker, Gias Uddin, and Anindya Iqbal delve into the crucial role that official documentation plays in the learning and utilization of an API. They highlight how API documentation, akin to source code, is a software product in itself and emphasize the detrimental impact that poorly designed documentation can have on the ease of reusing API features. Drawing parallels to code smells or antipatterns, the authors identify 'smells' in API documentation as indicators of bad documentation styles that hinder proper understanding and usability. The research conducted by Khan et al. focuses on addressing these documentation smells through the development of a catalog comprising five distinct types. To validate their findings, they meticulously examined 1,000 API documentation units within Java's official API reference and instruction documents. Additionally, a survey involving 21 professional software developers confirmed that these identified smells are prevalent in existing API documentation and significantly impede productivity. One notable aspect of this study is the absence of prior research on automatically detecting API documentation smells. To bridge this gap, the authors employ a combination of rule-based techniques and deep learning classifiers to create tools capable of identifying and rectifying these issues automatically. Their best-performing classifier, BERT - a deep learning model - achieves impressive F1-scores ranging from 0.75 to 0.97. Presented at the 2021 IEEE International Conference on Software Analysis, Evolution, and Reengineering (SANER), this paper sheds light on an often overlooked aspect of software development - the quality of API documentation. By providing insights into common pitfalls and offering solutions for improvement through automated detection methods, Khan et al. 's work aims to enhance developer experiences and streamline the utilization of APIs for more efficient software development practices.