Recommending Proper API Code Examples for Documentation Purpose

348 views

Published on

The work presentation on APSEC 2011

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
348
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
8
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Recommending Proper API Code Examples for Documentation Purpose

  1. 1. Recommending Proper API Code Examples for Documentation Purpose Lee Wei Mar, Ye-Chi Wu, and Hewijin Christine Jiau DBSE Lab @ Inst. CCE & Dept. EE National Cheng Kung University (NCKU), Taiwan
  2. 2. Outline• Introduction• Code Search Engines for Code Example Collection• The Proposed Methodology - PropER-Doc – Execution Process – Recommendation Assistants• Evaluation• Conclusion
  3. 3. Introduction• Nowadays, object-oriented frameworks & libraries offer powerful APIs that facilitate programmers in accomplishing their works
  4. 4. Introduction• Nowadays, object-oriented frameworks & libraries offer powerful APIs that facilitate programmers in accomplishing their works Power ↑ API Complexity ↑ Learning Barrier ↑
  5. 5. Introduction• Nowadays, object-oriented frameworks & libraries offer powerful APIs that facilitate programmers in accomplishing their works Hamper Power ↑ API Complexity ↑ Learning Barrier ↑
  6. 6. Introduction• Nowadays, object-oriented frameworks & libraries offer powerful APIs that facilitate programmers in accomplishing their works Hamper Power ↑ API Complexity ↑ Learning Barrier ↑To ensure the facilitation, offering effective API learning resourcesis essential for API providers
  7. 7. Introduction (cont.)• Code examples (CEs) are effective resources for API learning
  8. 8. Introduction (cont.)• Code examples (CEs) are effective resources for API learning Eclipse SWT public class Snippet26 { public static void main (String [] args) { Display display = new Display (); Shell shell = new Shell (display); Combo combo = new Combo (shell, SWT.READ_ONLY); combo.setItems (new String [] {"Alpha", "Bravo", "Charlie"}); Rectangle clientArea = shell.getClientArea (); combo.setBounds (clientArea.x, clientArea.y, 200, 200); shell.pack (); shell.open (); …. } Independent CE repository
  9. 9. Introduction (cont.)• Code examples (CEs) are effective resources for API learning Eclipse SWT Eclipse JDT public class Snippet26 { public static void main (String [] args) { Display display = new Display (); Shell shell = new Shell (display); Combo combo = new Combo (shell, SWT.READ_ONLY); combo.setItems (new String [] {"Alpha", "Bravo", "Charlie"}); Rectangle clientArea = shell.getClientArea (); combo.setBounds (clientArea.x, clientArea.y, 200, 200); shell.pack (); shell.open (); …. } Independent CE repository Embedding CE in API reference
  10. 10. Introduction (cont.)• Code examples (CEs) are effective resources for API learning Guide programmers to properly use API by demonstration
  11. 11. Introduction (cont.)• Code examples (CEs) are effective resources for API learning Guide programmers to properly use API by demonstration• However, many APIs fail to offer sufficient CEs
  12. 12. Introduction (cont.)• Code examples (CEs) are effective resources for API learning Guide programmers to properly use API by demonstration• However, many APIs fail to offer sufficient CEs API providers must invest large human effort for CE construction from scratch
  13. 13. CSEs for Code Example Collection• Code Search Engines (CSEs) are potentially useful in CE collection query API provider source files potentially use the API element
  14. 14. CSEs for Code Example Collection• Code Search Engines (CSEs) are potentially useful in CE collection query API provider source files potentially use the API elementThe signature of a specific API elementis given as the query keyword
  15. 15. CSEs for Code Example Collection• Code Search Engines (CSEs) are potentially useful in CE collection query API provider source files potentially use the API elementThe signature of a specific API elementis given as the query keyword • These files contain “client code” that demonstrates the use of the API element • The client code can be treated as “candidates” of CEs for documentation
  16. 16. CSEs for Code Example Collection - Challenges• Code Search Engines (CSEs) are potentially useful in CE collection query API provider source files potentially use the API element API providers must manually
  17. 17. CSEs for Code Example Collection - Challenges• Code Search Engines (CSEs) are potentially useful in CE collection query API provider source files potentially use the API element API providers must manually 1. Locate API usage code scattered in source files as candidates 2. Reorganize candidates according to different usages 3. Check appropriateness of candidates for documentation
  18. 18. CSEs for Code Example Collection - Challenges• Code Search Engines (CSEs) are potentially useful in CE collection query API provider source files potentially use the API element API providers must manually 1. Locate API usage code scattered in source files as candidates 2. Reorganize candidates according to different usages 3. Check appropriateness of candidates for documentation These manual efforts must be reduced to make such practice applicable
  19. 19. The Proposed Methodology – PropER-Doc• Proper code Example candidates Recommendation for Documentation – Use API element links to guide the recommendation from CSE results
  20. 20. The Proposed Methodology – PropER-Doc• Proper code Example candidates Recommendation for Documentation – Use API element links to guide the recommendation from CSE results Links between API elements to indicate the joint use relationship • Structural Links from structural dependencies in API implementation • Conceptual Links from cross references in API documentation
  21. 21. The Proposed Methodology – PropER-Doc• Proper code Example candidates Recommendation for Documentation – Use API element links to guide the recommendation from CSE results Links between API elements to indicate the joint use relationship • Structural Links from structural dependencies in API implementation • Conceptual Links from cross references in API documentation – Offer recommendation assistants for candidate inspection & selection
  22. 22. PropER-Doc Execution Process perform targetType query Candidate code search CollectionAPI Provider candidates check API call Candidate significance candidate suggestion Annotation annotated candidates Candidate Recommendation
  23. 23. PropER-Doc Execution Process perform targetType query Candidate code search CollectionAPI Provider
  24. 24. PropER-Doc Execution Process perform targetType query Candidate code search Collection API ProviderThe API provider gives a nameof the API type that needs CEs
  25. 25. PropER-Doc Execution Process perform targetType query Candidate code search Collection API ProviderThe API provider gives a nameof the API type that needs CEs The query is delegated to CSEs
  26. 26. PropER-Doc Execution Process perform targetType query Candidate code search Collection API Provider candidatesThe API provider gives a nameof the API type that needs CEs The query is delegated to CSEs • PropER-Doc collects candidates from CSE results • Candidate: a method implementation that refers targetType usage
  27. 27. PropER-Doc Execution Process perform targetType query Candidate code search CollectionAPI Provider candidates check API call Candidate significance Annotation
  28. 28. PropER-Doc Execution Process perform targetType query Candidate code search Collection API Provider candidates check API callFor each API call, annotate it with a Candidate significancesignificance degree Annotation 6 0 (relevant) (irrelevant)
  29. 29. PropER-Doc Execution Process perform targetType query Candidate code search Collection API Provider candidates check API callFor each API call, annotate it with a Candidate significancesignificance degree Annotation 6 0 (relevant) (irrelevant) annotated candidates
  30. 30. PropER-Doc Execution Process perform targetType query Candidate code search Collection API Provider candidates check API callcandidate suggestion Candidate significance Annotation annotated candidates Candidate Recommendation
  31. 31. PropER-Doc Execution Process perform targetType query Candidate code search Collection API Provider candidates check API callcandidate suggestion Candidate significance Annotation recommendationwithassistants annotated candidates Candidate Recommendation
  32. 32. Candidate RecommendationFour Recommendation Assistants are offered to guide the recommendation
  33. 33. Candidate Recommendation Four Recommendation Assistants are offered to guide the recommendation [All candidates] Grouping fordistinguishing API usages
  34. 34. Candidate Recommendation Four Recommendation Assistants are offered to guide the recommendation [All candidates] [A selected group] Grouping for Diagramming APIdistinguishing API usages types interaction
  35. 35. Candidate Recommendation Four Recommendation Assistants are offered to guide the recommendation [All candidates] [A selected group] [Candidates in a group] Grouping for Diagramming API Ranking based ondistinguishing API usages types interaction appropriateness metrics
  36. 36. Candidate Recommendation Four Recommendation Assistants are offered to guide the recommendation [All candidates] [A selected group] [Candidates in a group] [A selected candidate] Grouping for Diagramming API Ranking based on Presenting thedistinguishing API usages types interaction appropriateness metrics candidate for inspection
  37. 37. Recommendation - Clustering Grouping Diagramming Ranking Presenting[All candidates] – Distinguish different API usages
  38. 38. Recommendation - Clustering Grouping Diagramming Ranking Presenting[All candidates] – Distinguish different API usages Rationale: In different usages, targetType tends to interact with different API types
  39. 39. Recommendation - Clustering Grouping Diagramming Ranking Presenting[All candidates] – Distinguish different API usages Rationale: In different usages, targetType tends to interact with different API types • PropER-Doc extracts iTypes of each candidate – iTypes: the set of API types where targetType directly interacts with • Candidates with the same iTypes tend to demonstrate the same usage and are grouped together
  40. 40. Recommendation - Clustering Grouping Diagramming Ranking Presenting[All candidates] – Distinguish different API usages Rationale: In different usages, targetType tends to interact with different API types • PropER-Doc extracts iTypes of each candidate – iTypes: the set of API types where targetType directly interacts with • Candidates with the same iTypes tend to demonstrate the same usage and are grouped together
  41. 41. Recommendation - Clustering Grouping Diagramming Ranking Presenting[One group is selected for inspection]
  42. 42. Recommendation - Clustering Grouping Diagramming Ranking Presenting[One group is selected for inspection] Use visual notation to summarize API type interaction of a specific usage
  43. 43. Recommendation - Clustering Grouping Diagramming Ranking Presenting[One group is selected for inspection] Use visual notation to summarize API type interaction of a specific usage • Visual Grammar
  44. 44. Recommendation - Clustering Grouping Diagramming Ranking Presenting[One group is selected for inspection] Use visual notation to summarize API type interaction of a specific usage • Visual Grammar – Box: API Type
  45. 45. Recommendation - Clustering Grouping Diagramming Ranking Presenting[One group is selected for inspection] Use visual notation to summarize API type interaction of a specific usage • Visual Grammar – Box: API Type – Edge / Label: interaction / API calls
  46. 46. Recommendation - Clustering Grouping Diagramming Ranking Presenting[One group is selected for inspection] Use visual notation to summarize API type interaction of a specific usage • Visual Grammar – Box: API Type – Edge / Label: interaction / API calls – API call popularity
  47. 47. Recommendation - Clustering Grouping Diagramming Ranking Presenting[One group is selected for inspection] Use visual notation to summarize API type interaction of a specific usage • Visual Grammar – Box: API Type – Edge / Label: interaction / API calls – API call popularity
  48. 48. Recommendation - Clustering Grouping Diagramming Ranking Presenting[One group is selected for inspection] Use visual notation to summarize API type interaction of a specific usage • Visual Grammar – Box: API Type – Edge / Label: interaction / API calls – API call popularity • Selection of interested API calls for filtering candidates
  49. 49. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A set of similar candidates demonstrating the same usage is chosen]
  50. 50. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A set of similar candidates demonstrating the same usage is chosen] Which one is more appropriate for documentation and should be inspected first?
  51. 51. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A set of similar candidates demonstrating the same usage is chosen] Define three appropriateness metrics to rank the candidates
  52. 52. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A set of similar candidates demonstrating the same usage is chosen] Define three appropriateness metrics to rank the candidates Significance Density Cohesiveness Importance of referred API calls Portion of relevant API calls Degree of relevant call aggregation > > > more more representative comprehensible easier extraction Candidate Statements with significance degree 6 0
  53. 53. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A set of candidates is chosen] Rank function: f(c) = Significance(c) + Density(c) + Cohesiveness(c)
  54. 54. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A candidate is selected for inspection & CE construction]
  55. 55. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A candidate is selected for inspection & CE construction] Highlight relevant code place to facilitate code inspection & extraction
  56. 56. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A candidate is selected for inspection & CE construction] Highlight relevant code place to facilitate code inspection & extraction
  57. 57. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A candidate is selected for inspection & CE construction] Highlight relevant code place to facilitate code inspection & extraction Important code blocks are highlighted
  58. 58. Recommendation - Clustering Grouping Diagramming Ranking Presenting[A candidate is selected for inspection & CE construction] Highlight relevant code place to facilitate code inspection & extraction Key API elements are marked as bold Important code blocks are highlighted
  59. 59. Evaluation• Objective: check PropER-Doc effectiveness on A. Distinguishing different API usages among candidates B. Suggesting proper candidates for CEs construction• Procedure 1. For an API type, manually identify its typical usages (U1) that need CEs 2. Use PropER-Doc to collect candidates and distinguish the API type usages (U2) 3. Map between U1 and U2 (objective A) 4. For each usage in U1, use PropER-Doc to select the top-ranked candidate 5. Evaluate the effort for constructing CE from top-ranked candidate (objective B)• Subject: ASTParser class (A complex API type in Eclipse JDT framework)
  60. 60. Evaluation Result – Mapping ResultU1 U2 (GID)Get AST from ICompilationUnit 1Get AST from a string of class body 2Get AST from a string of statements 3Get AST from a string of expression 4Get AST from ITypRoot 5Get IJavaElement binding info. 6Get AST from source code 7Get ASTs from ICompilationUnits 8Get AST from IClassFile 9
  61. 61. Evaluation Result – Mapping ResultU1 U2 (GID) • Mostly 1 : 1 mappingGet AST from ICompilationUnit 1Get AST from a string of class body 2Get AST from a string of statements 3Get AST from a string of expression 4Get AST from ITypRoot 5Get IJavaElement binding info. 6Get AST from source code 7Get ASTs from ICompilationUnits 8Get AST from IClassFile 9
  62. 62. Evaluation Result – Mapping ResultU1 U2 (GID) • Mostly 1 : 1 mappingGet AST from ICompilationUnit 1 – Confirm the effectiveness of theGet AST from a string of class body 2 grouping assistant in PropER-DocGet AST from a string of statements 3Get AST from a string of expression 4Get AST from ITypRoot 5Get IJavaElement binding info. 6Get AST from source code 7Get ASTs from ICompilationUnits 8Get AST from IClassFile 9
  63. 63. Evaluation Result – Mapping ResultU1 U2 (GID) • Mostly 1 : 1 mappingGet AST from ICompilationUnit 1 – Confirm the effectiveness of theGet AST from a string of class body 2 grouping assistant in PropER-DocGet AST from a string of statements 3Get AST from a string of expression 4 • For the 3 : 1 mapping, the diagramming assistant is useful inGet AST from ITypRoot 5 distinguishing different usagesGet IJavaElement binding info. 6Get AST from source code 7Get ASTs from ICompilationUnits 8Get AST from IClassFile 9
  64. 64. Evaluation Result – Mapping ResultU1 U2 (GID) • Mostly 1 : 1 mappingGet AST from ICompilationUnit 1 – Confirm the effectiveness of theGet AST from a string of class body 2 grouping assistant in PropER-DocGet AST from a string of statements 3Get AST from a string of expression 4 • For the 3 : 1 mapping, the diagramming assistant is useful inGet AST from ITypRoot 5 distinguishing different usagesGet IJavaElement binding info. 6Get AST from source code 7Get ASTs from ICompilationUnits 8Get AST from IClassFile 9 The Grouping and Diagramming assistants are useful in distinguishing different API usages
  65. 65. Evaluation Result – Constructing EffortU1 ∆Stmt (+/-) Coh.Get AST from ICompilationUnit 0/0 1.00Get AST from a string of class body 0/0 1.00Get AST from a string of statements 0/0 1.00Get AST from a string of expression 4/0 1.00Get AST from ITypRoot 0/1 1.00Get IJavaElement binding info. 3/0 1.00Get AST from source code 0/0 1.00Get ASTs from ICompilationUnits 16 / 0 0.63Get AST from IClassFile 0/0 1.00∆Stmt (+/-): #(extra statements) / #(missed statements)Coh.: Cohesiveness (between 0 and 1)
  66. 66. Evaluation Result – Constructing EffortU1 ∆Stmt (+/-) Coh. • 5 of 9 top candidates can beGet AST from ICompilationUnit 0/0 1.00 directly used as CEsGet AST from a string of class body 0/0 1.00Get AST from a string of statements 0/0 1.00Get AST from a string of expression 4/0 1.00Get AST from ITypRoot 0/1 1.00Get IJavaElement binding info. 3/0 1.00Get AST from source code 0/0 1.00Get ASTs from ICompilationUnits 16 / 0 0.63Get AST from IClassFile 0/0 1.00∆Stmt (+/-): #(extra statements) / #(missed statements)Coh.: Cohesiveness (between 0 and 1)
  67. 67. Evaluation Result – Constructing EffortU1 ∆Stmt (+/-) Coh. • 5 of 9 top candidates can beGet AST from ICompilationUnit 0/0 1.00 directly used as CEsGet AST from a string of class body 0/0 1.00Get AST from a string of statements 0/0 1.00 • Only 1 top candidate misses 1 statement for CE constructionGet AST from a string of expression 4/0 1.00 – Top candidates contains almost allGet AST from ITypRoot 0/1 1.00 required API calls for CE constructionGet IJavaElement binding info. 3/0 1.00Get AST from source code 0/0 1.00Get ASTs from ICompilationUnits 16 / 0 0.63Get AST from IClassFile 0/0 1.00∆Stmt (+/-): #(extra statements) / #(missed statements)Coh.: Cohesiveness (between 0 and 1)
  68. 68. Evaluation Result – Constructing EffortU1 ∆Stmt (+/-) Coh. • 5 of 9 top candidates can beGet AST from ICompilationUnit 0/0 1.00 directly used as CEsGet AST from a string of class body 0/0 1.00Get AST from a string of statements 0/0 1.00 • Only 1 top candidate misses 1 statement for CE constructionGet AST from a string of expression 4/0 1.00 – Top candidates contains almost allGet AST from ITypRoot 0/1 1.00 required API calls for CE constructionGet IJavaElement binding info. 3/0 1.00Get AST from source code 0/0 1.00 • High cohesiveness in all top candidatesGet ASTs from ICompilationUnits 16 / 0 0.63 – Effort for relevant code extractionGet AST from IClassFile 0/0 1.00 from top candidates is quite low∆Stmt (+/-): #(extra statements) / #(missed statements)Coh.: Cohesiveness (between 0 and 1)
  69. 69. Evaluation Result – Constructing EffortU1 ∆Stmt (+/-) Coh. • 5 of 9 top candidates can beGet AST from ICompilationUnit 0/0 1.00 directly used as CEsGet AST from a string of class body 0/0 1.00Get AST from a string of statements 0/0 1.00 • Only 1 top candidate misses 1 statement for CE constructionGet AST from a string of expression 4/0 1.00 – Top candidates contains almost allGet AST from ITypRoot 0/1 1.00 required API calls for CE constructionGet IJavaElement binding info. 3/0 1.00Get AST from source code 0/0 1.00 • High cohesiveness in all top candidatesGet ASTs from ICompilationUnits 16 / 0 0.63 – Effort for relevant code extractionGet AST from IClassFile 0/0 1.00 from top candidates is quite low PoperER-Doc suggests high quality candidates for CEs construction
  70. 70. Conclusion• PropER-Doc is proposed to assist API providers in constructing proper API code examples using code search engines 1. Candidate grouping algorithm 2. API-type interaction diagram 3. Metrics-based ranking mechanism
  71. 71. Conclusion• PropER-Doc is proposed to assist API providers in constructing proper API code examples using code search engines 1. Candidate grouping algorithm Distinguish different API usages 2. API-type interaction diagram 3. Metrics-based ranking mechanism
  72. 72. Conclusion• PropER-Doc is proposed to assist API providers in constructing proper API code examples using code search engines 1. Candidate grouping algorithm Distinguish different API usages 2. API-type interaction diagram Inspect specific usage & filter candidates 3. Metrics-based ranking mechanism
  73. 73. Conclusion• PropER-Doc is proposed to assist API providers in constructing proper API code examples using code search engines 1. Candidate grouping algorithm Distinguish different API usages 2. API-type interaction diagram Inspect specific usage & filter candidates 3. Metrics-based ranking mechanism Select high quality candidates
  74. 74. Conclusion• PropER-Doc is proposed to assist API providers in constructing proper API code examples using code search engines 1. Candidate grouping algorithm Distinguish different API usages 2. API-type interaction diagram Inspect specific usage & filter candidates 3. Metrics-based ranking mechanism Select high quality candidates• Evaluation on Eclipse JDT framework has been conducted to confirm the effectiveness of PropER-Doc
  75. 75. Thank You Lee Wei Mar (馬立偉) lwmar@nature.ee.ncku.edu.tw Database and Software Engineering Laboratory,Institute of Computer and Communication Engineering & Department of Electrical Engineering, National Cheng Kung University, Tainan, Taiwan

×