Analyzing APIs Documentation and Code to Detect Directive Defects
Open accessThe DOI matches its Crossref record; 3 of the 3 references it cites were found in a registry or an index.
Abstract
Application Programming Interface (API) documents represent one of the most important references for API users. However, it is frequently reported that the documentation is inconsistent with the source code and deviates from the API itself. Such inconsistencies in the documents inevitably confuse the API users hampering considerably their API comprehension and the quality of software built from such APIs. In this paper, we propose an automated approach to detect defects of API documents by leveraging techniques from program comprehension and natural language processing. Particularly, we focus on the directives of the API documents which are related to parameter constraints and exception throwing declarations. A first-order logic based constraint solver is employed to detect such defects based on the obtained analysis results. We evaluate our approach on parts of well documented JDK 1.8 APIs. Experiment results show that, out of around 2000 API usage constraints, our approach can detect 1158 defective document directives, with a precision rate of 81.6%, and a recall rate of 82.0%, which demonstrates its practical feasibility.
Overview
The claims and statistics of this paper haven’t been checked yet.
Free: it reads the open-access text and checks the first 5 claims that cite a source we can check. Create a free account to check every claim.
Integrity signals
Registry
Cites
Statistics
Verification
Claims the paper makes
The claims and statistics of this paper haven’t been checked yet.
Free: it reads the open-access text and checks the first 5 claims that cite a source we can check. Create a free account to check every claim.
Self-check
Percentages, sums and reported differences re-computed from the paper’s own numbers.
The self-check needs the paper’s full text.
Citations
Cites
de Moura, L., & Bjørner, N. (2008) · Lecture Notes in Computer Science · doi:10.1007/978-3-540-78800-3_24 · Cited by 6,595 · cited 1×
“, Z3 [10], to detect the defects in case of inconsistency.”
BackgroundThe relevance of software documentation, tools and technologies: a survey
Forward, A., & Lethbridge, T. C. (2002) · Proceedings of the 2002 ACM symposium on Document engineering · doi:10.1145/585058.585065 · Cited by 268 · cited 1×
“In most cases, such implicit exceptions are caused by programming errors, so it might be inappropriate to include them in the documentation [15].”
BackgroundWhat help do developers seek, when and how?
Li, H., Xing, Z., Peng, X., & Zhao, W. (2013) · 2013 20th Working Conference on Reverse Engineering (WCRE) · doi:10.1109/wcre.2013.6671289 · Cited by 81
Research works printed but not linked: 38
- 10.1109/SANER.2017.7884612 · DOI
- 10.1109/ICSE-C.2017.5 · DOI
- 10.1109/ICSE.2015.97 · DOI
- 10.1007/s10664-014-9323-y · DOI
- 10.1109/TSE.2014.2347969 · DOI
- 10.1109/ICSE.2013.6606629 · DOI · Paper page
- di, 2016, What would users change in my app? summarizing app reviews for recommending software changes, Foundations of Software Engineering (FSE) 2016 ACM SIGSOFT International Symposium on the
- 10.1109/ICPC.2013.6613842 · DOI
- 10.1145/2597008.2597799 · DOI
- 10.1109/ICPC.2012.6240510 · DOI
- 10.1109/ICSM.2015.7332474 · DOI · Paper page
- 10.1109/ASE.2015.12 · doi:10.1109/ase.2015.12
- sorbo, 2016, DECA: development emails content analyzer, Proceedings of the 38th International Conference on Software Engineering ICSE 2016, 641
- barrett, 2009, Satisfiability modulo theories, Handbook of Satisfiability, 185, 825
- feldt, 2010, Validity threats in empirical software engineering research-an initial survey, SEKE, 374
- 10.1145/1390630.1390664 · DOI · Paper page
- lam, 2011, The soot framework for java program analysis: a retrospective, Cetus Users and Compiler Infastructure Workshop (CETUS 2011)
- shi, 2011, An empirical study on evolution of api documentation, FASE, 6603, 416
- 10.1145/1882291.1882312 · DOI · Paper page
- 10.1109/ASE.2009.94 · DOI · Paper page
- 10.1145/2597008.2597155 · DOI · Paper page
- 10.1109/TSE.2012.63 · DOI · Paper page
- 10.1109/SANER.2015.7081813 · doi:10.1109/saner.2015.7081813
- 10.1109/ICSE.2012.6227137 · DOI
- 10.1109/MS.2014.80 · DOI · Paper page
- 10.1145/2568225.2568299 · DOI · Paper page
- bloch, 2006, How to design a good api and why it matters, Companion to the 21 st ACM SIGPLAN symposium on Object-oriented programming systems languages and applications, 506
- 10.1145/2775441.2775457 · DOI
- 10.1007/s10664-011-9186-4 · DOI
- 10.1109/ESEM.2013.14 · DOI · Paper page
- 10.1007/s10664-014-9350-8 · DOI
- 10.1145/1294261.1294276 · DOI · Paper page
- zhong, 2013, Detecting api documentation errors, ACM SIGPLAN Notices, 48, 803, 10.1145/2544173.2509523 · DOI
- 10.1109/ICST.2012.106 · DOI · Paper page
- 10.1145/2950290.2983938 · DOI
- 10.1145/1985793.1985796 · DOI · Paper page
- 10.1145/2642937.2642969 · DOI
- 10.1109/ICPC.2013.6613836 · DOI · Paper page
Cited by
A Large-Scale Empirical Study on Code-Comment Inconsistencies
Wen, F., Nagy, C., Bavota, G., & Lanza, M. (2019) · 2019 IEEE/ACM 27th International Conference on Program Comprehension (ICPC) · doi:10.1109/icpc.2019.00019 · Cited by 105
Automating just-in-time comment updating
Liu, Z., Xia, X., Yan, M., & Li, S. (2020) · Proceedings of the 35th IEEE/ACM International Conference on Automated Software Engineering · doi:10.1145/3324884.3416581 · Cited by 56
Predictive Comment Updating With Heuristics and AST-Path-Based Neural Learning: A Two-Phase Approach
Lin, B., Wang, S., Liu, Z., Xia, X., & Mao, X. (2023) · IEEE Transactions on Software Engineering · doi:10.1109/tse.2022.3185458 · Cited by 27
“[74] focused on defects of Application Programming Interface (API) documentation and detected such issues based on the analysis results from a constraint solver.”
MethodGenerating Unit Tests for Documentation
Nassif, M., Hernandez, A., Sridharan, A., & Robillard, M. P. (2022) · IEEE Transactions on Software Engineering · doi:10.1109/tse.2021.3087087 · Cited by 22
“ness of the documentation, another challenging problem [49], [50].”
BackgroundLeveraging Large Language Model to Assist Detecting Rust Code Comment Inconsistency
Zhang, Y., Liu, Z., Feng, Y., & Xu, B. (2024) · Proceedings of the 39th IEEE/ACM International Conference on Automated Software Engineering · doi:10.1145/3691620.3695010 · Cited by 10
Metadata
- Authors
- Zhou, Y., Gu, R., Chen, T., Huang, Z., Panichella, S., & Gall, H.
- Venue
- 2017 IEEE/ACM 39th International Conference on Software Engineering (ICSE)
- Publisher
- IEEE
- Published
- 2017-05
- Pages
- 27-37
- OpenAlex
- W2617604339
- Cited by
- 115
- References
- 3
- FWCI
- 9.74
- Type
- conference paper
- Language
- en
- Open access
- green
About these checks
Registry, retraction, Cites and statistics results are computed, not judged, with one exception: a printed reference that no index lists is read once by a model before it counts as a citation error. Claims are extracted by a model and kept only when their quote appears verbatim in the text; each cited source is then checked, with a model’s help, for whether it says what the claim relies on. Those verdicts can be wrong — read the claim’s quote and the cited source before relying on one.
Statistics and arithmetic are recomputed, not judged.
Confidence bands are shown only for fields calibrated on our annotated test set. None is calibrated yet, so no band is shown.
What counts as a claim ›How we measure confidence ›How we check this ›
Are you an author, or do you see a problem with this page? Request a review
How to cite
Cite CoChat for the checks on this page, and the paper for its own findings.
- This page
- CoChat. (2026). Citation check: Analyzing APIs Documentation and Code to Detect Directive Defects. https://app.cochat.ai/papers/10.1109/icse.2017.11
- The paper
- Zhou, Y., Gu, R., Chen, T., Huang, Z., Panichella, S., & Gall, H. (2017). Analyzing APIs Documentation and Code to Detect Directive Defects. 2017 IEEE/ACM 39th International Conference on Software Engineering (ICSE). https://doi.org/10.1109/icse.2017.11
Data sources
Bibliographic data: Semantic Scholar, OpenAlex, Crossref.
Contains information from the Semantic Scholar Academic Graph Datasets, made available under the ODC Attribution License (ODC-BY 1.0).
Semantic Scholar’s data is described in: Kinney, R., et al. (2023). The Semantic Scholar Open Data Platform. arXiv:2301.10140.