Home

ActiveDocumentation

ActiveDocumentation is a two-component application, consisting of an IDE plugin and a web app. It communicates with the IDE Connector using WebSockets, currently operating on port 8887.

Components

IDE Plugin

The IDE plugin is responsible for transferring data between the app and the IDE, as well as handling functionalities that cannot be managed by the web app. Two plugins have been developed for ActiveDocumentation: IntelliJ and VS Code.

Web App

The web app is built using the React framework. It handles all computations and renders the data.

Code Representation and Design Rules

ActiveDocumentation translates the codebase into XML format using the srcML library. Design rules can be expressed as XPath queries based on srcML tags.

Design Decisions

Documented design decisions, including design rules and other information, are stored in a file named ruleTable.json. This file is located in the root directory of each project. Each design decision is a JSON object with the following properties:

• index: string, the unique identifier of a design decision, usually a number.
• title: string, a short summary of the design decision, displayed in the table of contents and the header of design decision panels.
• description: string, a detailed description of the design decision, which can include any relevant information. This information is also sent to LLMs for suggested fixes.
• tags: string[], a list of tags manually assigned to a design decision.
• checkForFilesFoldersConstraints: "INCLUDE" | "EXCLUDE" | "NONE"
  • "INCLUDE": The design decision only applies to the listed packages and files.
  • "EXCLUDE": The design decision applies to all packages and files except the listed ones.
  • "NONE": The design decision applies to all packages and files.
• checkForFilesFolders: string[], a list of packages and/or files.
• processFilesFolders: "WITHIN" | "MIXED"
  • "WITHIN": The tool executes XPath queries of a design rule for each file independently.
  • "MIXED": When a design rule has multiple queries, the tool executes the queries in order and on different files.
• quantifierXPathQuery: string[], a list of XPath queries defined as the quantifier of a design rule.
• constraintXPathQuery: string[], a list of XPath queries defined as the constraints of a design rule.
• constraintQueryType: "NEXT" | "FIRST"
  • "NEXT": When there are two constraint queries, each query is executed on a different file.
  • "FIRST": When there are three constraint queries, the third query is run against the first file again.

Tags

Documented tags are stored in tagTable.json, located in the root directory of each project. Each tag is stored as a JSON object with the following properties:

• ID: string, the unique identifier, typically a number.
• tagName: string, the name of the tag.
• detail: string, the description of the tag.