1 引用
Lijie Wang and Lu Fang and Leye Wang and Ge Li and Bing Xie and Fuqing Yang. APIExample: An effective web search based usage example recommendation system for java APIs. In Proceedings of the 26th International Conference on Automated Software Engineering, 2011, 592-595.
2 摘要
程序員經常通過學習 API 的使用示例來學習如何使用它。因特網上的網頁上散佈著許多使用實例。然而，通過網絡搜索從大量的 web 頁面中找出所需的示例通常需要程序員付出很大的努力。本文提出了一個名為 APIExample 的工具，它可以從因特網上的 web 頁面中提取 java API 的使用示例並推薦給程序員。給定一個 java API，該工具從網絡上收集相關的 web 頁面，提取嵌入頁面中的 java 代碼片段及其周圍的描述性文本，然後將它們組合成程序員的使用示例。此外，為了幫助程序員通過瀏覽更少的示例來獲取更多類型的目標 API 用法，我們的工具將根據目標 API 的用法對列出的示例進行聚類和排序。此外，作為一個實用的工具，APIExample 在一個簡潔的用戶界面中提供了有關使用目標 API 的多個方面的常用信息，並提供了友好的用戶體驗。兩種用戶交互風格，web 搜索門戶和 Eclipse 插件，現在都是公開可用的。
3 APIEXAMPLE 概述
在本節中，我們以 APIExample 的 Web 搜索門戶用戶界面為例簡要介紹 APIExample 的功能，有關該工具演示的詳細信息，請訪問網站。
提交“java.io.BufferedReader”查詢後，將返回 API 的用法示例和其他與用法有關的信息，如圖 1 所示。所提供的用法示例都是從互聯網上的網頁中自動提取的。
圖 1 java.io.BufferedReader 的用法示例搜索結果
4 方法
如圖 2 所示，APIExample 背後的方法包括四個主要階段：（1）網頁收集，（2）使用示例提取，（3）示例聚類和排名以及（4）統計分析。
圖 2 APIExample 背後方法的過程
4.1 網頁收集
給定一個 API，APIExample 通過利用 “APIFQN” example java 的格式構造查詢，利用 Google 從互聯網上收集相關的 web 頁面，其中 APIFQN 是給定 API 的全限定名，術語“example”和“java”用於限制搜索範圍。結果列表中的前 N 個（當前為 300 個）網頁被下載為目標 API 的相關網頁。
4.2 使用示例例提取
這個階段包括三個步驟：1）網頁分割；2）代碼片段識別；3）描述性文本提取。
1）網頁分割
此步驟根據 HTML 文檔結構將網頁的文本內容拆分為頁段。我們將幾個特定的標記看作段符號，包括 P、DIV、TABLE、TR、PRE、CODE、OL、UL、LI 和 Heading 標記（H1~H6），因為它們通常用作內容段的容器。嵌入在這些標記中的文本內容被視為一個段。當其他標記的文本內容保留給其父標記時，這些標記將被刪除。
2）代碼片段識別
對於每個頁面段，我們通過兩個步驟判斷它是否是代碼段：a）使用啟發式方法初步確定該段是否“看起來”是代碼段；b）使用可適應的解析器解析可能的代碼段以做出最終決定，同時提取代碼段的細粒度結構信息。
在這一步中，在解析階段生成的細粒度編程結構信息（例如使用了哪些 APIs，在哪一行調用了哪些方法，聲明瞭哪些方法）將被記錄到以下階段。
3）描述性文本提取
遍歷每個網頁的段列表，當遇到一個代碼段時，我們使用以下策略提取其前面的描述性文本：迭代合併代碼段前面的段，直到滿足以下條件之一：1）遇到另一個代碼段。2） 合併的描述性文本的長度達到給定的閾值（當前為 250 個術語）3）遇到內容中斷的符號。以下標籤被視為中斷符號：DIV、TABLE、HR、UL、OL、H1~H6。
對於代碼後面的描述性文本，根據觀察結果，如果緊跟在代碼片段後面的文本段提到代碼塊聲明的編程元素，我們將嘗試提取它們。然後，我們使用與前面的文本提取相似的策略來提取代碼片段後面的描述性文本。
4.3 示例聚類和排名
由於 web 搜索返回的結果非常龐大，因此使用示例的數量通常非常大。實際上，它們中的許多演示了目標 API 的類似用法。要了解如何使用 API，程序員通常需要掌握 API 的多種用法。為了減少程序員在探索許多重複結果時所需的工作量，我們對收集到的使用示例進行聚類和排序。這一點很重要，因為在 web 搜索過程中，程序員在理解大量搜索結果時的認知負擔一直是一個很大的問題，使他們難以處理信息。
應用 API 來完成不同任務的人通常會調用 API 的不同方法集。因此，我們將對每個示例的代碼片段公開的目標 API 方法的調用作為使用特性。然後我們利用這個特性計算任意兩個使用示例之間的相似性。調用目標 API 的相同方法集的兩個示例將集群到一個類別中。
排名包括兩部分：1）簇間排名，即對使用簇進行排名；2）簇內排名，即對使用簇中的使用實例進行排名。
4.4 統計分析
基於上述階段產生的數據，我們對 API 的使用相關信息進行統計分析，包括 API 的不同用法分佈、API 的每個方法的調用頻率以及常用的 APIs。分析結果存儲在數據庫中，以及用於檢索的使用示例。
5 本文主要貢獻
本文提出了一個實用工具 APIExample，它提供了一個基於 web 搜索的 java API 使用實例的完整視圖。為了幫助程序員從大量的網頁中輕鬆地找出 API 的使用示例，該工具自動識別並從相關網頁中提取其使用示例，同時消除不相關的噪音。該工具不僅可以提取代碼片段，還可以正確提取可讀的描述性文本。這使得使用示例更容易理解，程序員可以在不干擾無關信息的情況下查看它們。為了減少程序員查看許多重複結果的負擔，APIExample 對收集到的使用示例進行基於使用的集群和排名。有了這種支持，程序員可以通過瀏覽更少的結果來研究目標 API 的更多種用法。此外，通過對收集到的實例的分析，APIExample 可以直接告訴程序員哪些 API 的用法經常出現在互聯網上，哪些 API 的方法經常使用，哪些 API 經常與 API 一起使用。這些信息有助於指導程序員更好地瞭解 API。所有這些與使用相關的信息都以簡潔的用戶界面和友好的用戶體驗呈現給程序員。該工具現在可在http://www.apiexample.com上獲得。
致謝
感謝國家重點研發計劃課題：基於協同編程現場的智能實時質量提升方法與技術（2018YFB1003901）和國家自然科學基金項目：基於可理解信息融合的人機協同移動應用測試研究（61802171）支持！
本文由南京大學軟件學院 2018 級碩士生韓奇翻譯轉述。
閱讀更多 慕測科技 的文章
