Building Documentation Generators

1
Building Documentation Generators

• Arie van Deursen
• Tobias Kuipers
• CWI, The Netherlands

2
Documentation

• Maintenance outsourcing increases demand for
  documentation
• Software company asked us whether we could
  generate documentation
• Our reverse engineering results can be
  intuitively presented as (a particular form of)
  documentation

3
Documentation Challenges

• Should be available at different levels of
  abstraction
• User must be able to move between different
  abstractions
• Abstraction level should be meaningful to user
• Needs to be consistent with source code

4
Tool Architecture
5
Source Code Analysis

• Lexical Analysis (regular expressions)
• CALL A-Z
• Syntactical Analysis
• CALL FOO
• CALL FOO USING ...
• CALL \n FOO

6
Combine lexical and syntactical
syntax \n \n -gt LAYOUT A-Z
-gt Id \. . -gt Statement
CALL Id . -gt Statement Statement
-gt Program priorities CALL Id . -gt
Statement gt \. . -gt Statement
7
Example Analysis

• MOVE 1 TO A .
• This is some comment
• CALL
• Strange place for comment
• FOO .
• PERFORM BAR .

8
Example Analysis

• MOVE 1 TO A .
• This is some comment
• CALL
• Strange place for comment
• FOO .
• PERFORM BAR .

9
Example Analysis

• MOVE 1 TO A .
• This is some comment
• CALL
• Strange place for comment
• FOO .
• PERFORM BAR .

10
Example Analysis

• MOVE 1 TO A .
• This is some comment
• CALL
• Strange place for comment
• FOO .
• PERFORM BAR .

11
Island Grammars

• Detailed production rules for relevant constructs
• Catch-all productions with lower priority
• Minimal set of productions for overall program
  structure
• Used for rapid/specific parser development

12
Repository and Presentation

• Standard tools
• Relational database
• Hypertext browser
• Different levels of abstraction
• Preformulated queries presented as hypertext to
  maintenance programmer
• Reengineer can formulate own queries on database
• Demo

13
Contributions

• Island Grammars for fact extraction
• Integration of hand-written facts/documentation
• Explicit Repository/Data model
• Flexible formatting
• Integration of visual/textual presentation
• Applied in several commercial projects