Automatic Code Documentation from Usage Patterns
Find Innovative SolutionsGenerate Solutions
Solution Overview
Problem
Software code documentation is often insufficient, with developers neglecting to provide comprehensive external documentation, and existing methods struggle to identify important parts of the code to document effectively.
Innovation Solution
A method and system for generating documentation text by extracting element identifiers from source files, computing scores based on connections and appearances, and using patterns in usage instances to create accurate and usable documentation.
Engineering Contradictions & Design Principles
Engineering Contradiction Analysis
1Loss of information
If developers add comments inside the code to describe elements, then local information is provided, but comprehensive documentation covering general aspects is insufficient
Solution Approach 1:
The system segments documentation into two distinct types: inline code comments for local element information and external documentation files for comprehensive general aspects. This segmentation allows each type to serve its specific purpose effectively, resolving the contradiction between providing local information and covering general aspects comprehensively.
Solution Approach 2:
The system introduces an intermediary documentation structure that connects inline comments with external documentation. The inline comments reference external documentation files, and the external documentation aggregates information from multiple sources, creating a bridge between local and global documentation needs.
2Reliability
If developers write sufficient documentation, then knowledge is preserved and shared, but time and effort are consumed
Solution Approach 1:
The system performs preliminary extraction of element identifiers and automatic generation of documentation structure before the developer needs to write content. By pre-organizing the documentation framework and identifying all elements that need documentation, the system reduces the time and effort required during the actual documentation writing phase.
Solution Approach 2:
The system enables self-service documentation generation by automatically extracting element identifiers from code, computing their significance scores, and organizing them into a documentation structure. This automation reduces the manual effort developers would otherwise need to spend on documentation while maintaining comprehensive coverage.
3Loss of information
If all element identifiers are documented, then completeness is achieved, but accuracy of identifying significant elements decreases
Solution Approach 1:
The system changes the parameter of element selection by computing significance scores based on multiple factors including connection amounts and appearance frequencies. Instead of documenting all elements equally, the system uses these computed parameters to identify and prioritize significant elements for documentation, thereby maintaining both coverage and precision.
4Productivity
If documentation is generated without using patterns, then generation speed is faster, but accuracy and consistency of documentation decreases
Solution Approach 1:
The system uses pattern matching to identify recurring code structures and documentation patterns. By copying proven documentation templates and patterns for common element types, the system maintains high accuracy and consistency while preserving fast generation speeds. The patterns serve as reusable templates that ensure quality without requiring manual review of each documentation instance.
Data Source
AI summary
A method for generating documentation text comprises: extracting, from a plurality of source files of a software program, a plurality of element identifiers, each identifying an element of the software program; selecting a set of selected element identifiers of the plurality of element identifiers according to a plurality of scores, each score computed for an element identifier of the plurality of element identifiers; and for each of the set of selected element identifiers: generating an element documentation text using a documentation template and a plurality of patterns identified in a plurality of usage instances where in each of the plurality of usage instances the selected element identifier exists in at least one of the plurality of source files; and adding the element documentation text to a repository of documentation text associated with the plurality of source files.