Skip to content

Commit

Permalink
Add code explorer documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
dpolivaev committed Mar 16, 2024
1 parent 143498e commit ebce018
Show file tree
Hide file tree
Showing 8 changed files with 129 additions and 1 deletion.
2 changes: 2 additions & 0 deletions src/docs/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@
- [Relationship to FreeMind](user-documentation/Relationship_to_FreeMind.md)
- [References to other known documentation/tutorial sites](user-documentation/other-docs-tutorials.md)
- [Mind map examples](user-documentation/mind-map-examples.md)
- [Code explorer](user-documentation/Code_Explorer.md)
- [ArchUnit Test Result Viewer](user-documentation/ArchUnit_Extension.md)
- [Contribute](contribute/contribute.md)
- [Translation How-To](contribute/Translation_How-To.md)
- [Scripting](scripting/Scripting.md)
Expand Down
2 changes: 1 addition & 1 deletion src/docs/attic/new-wiki-initiative/understanding-nodes.md
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@ Other nodes can also be given the style `Floating node` and can be set to be pos
### Node groups
#### Summary nodes

![](images/nodes_summary_nodes.png ':size=200')
![Summary nodes](images/nodes_summary_nodes.png ':size=200')

Summary nodes have brackets that suggest that their content summarizes a group of sibling nodes.
Technically, summary nodes are specially marked sibling nodes of the summarized nodes.
Expand Down
Binary file added src/docs/images/architectureViolations.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/docs/images/codemap.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/docs/images/dependencies.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
34 changes: 34 additions & 0 deletions src/docs/user-documentation/ArchUnit_Extension.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Arch Unit Test Result Viewer

## Introduction

The Architecture Violations feature in Freeplane's Code Explorer mode is used to capture and display rule violations that are identified during the code analysis process. This is specifically related to the integration with the Freeplane ArchUnit extension.

## Architecture Violations Tab

![Architecture Violations](../images/architectureViolations.jpg)

### Overview

The Architecture Violations tab provides a mechanism to record and display violations reported by the ArchUnit tests.

### Buttons and Their Functions

- **Record ArchUnit Test Results**: This button starts a listener that receives test results from the Freeplane ArchUnit Extension.
- **Delete Configuration**: Removes the currently selected violation configuration.
- **Run Analysis**: Performs the analysis again to detect architecture violations. Double-click on the configuration has the same result.
- **Cancel**: Halts any ongoing analysis process.

### Violations Reporting

- Violated rules are reported and can be visualized as maps within the Architecture Violations tab.
- These violations are not saved across Freeplane restarts and are only available during the current session.

### Additional Information

- For persistent records of violations, users should manually save or document the information prior to exiting Freeplane.
- Detailed setup and usage guidelines for the Freeplane ArchUnit Extension are available on its [GitHub repository](https://github.com/freeplane/freeplane-archunit-extension).

## Note

Please ensure that the Freeplane ArchUnit Extension is correctly installed and configured to utilize the Architecture Violations feature effectively.
90 changes: 90 additions & 0 deletions src/docs/user-documentation/Code_Explorer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@

<!-- toc -->

# Freeplane Code Explorer Mode Documentation

## Introduction

The Code Explorer mode in Freeplane is designed for analyzing the structure and dependencies of code compiled to JVM class files.

![Code map](../images/codemap.png)

## Accessing Code Explorer Mode

1. Launch Freeplane version 1.11.12 or later.
2. Navigate to the menu bar at the top of the application.
3. Click on `Maps`.
4. Select `Modes`.
5. Choose `Code Explorer` to enter the code explorer mode.

## Video Tutorials

Video tutorials are available to help users familiarize themselves with the Code Explorer mode. To access the tutorial, navigate to the Help menu within Freeplane and select Help -> Code Explorer Introduction Video.

## Configurations Panel

### Configurations Tab

The Configurations tab allows users to manage their configurations and consists of three parts: configurations, locations, and rules.

#### Configurations

- **Add Configuration**: Click this button to create a new configuration.
- **Delete Configuration**: Use this button to remove the currently selected configuration.
- **Run Analysis**: Initiates the analysis process, loading and importing class files.
- **Apply Changes**: Attempts to apply only rule changes without reloading class files, if there are no location changes.
- **Cancel**: Allows users to cancel an analysis that has started but not yet finished.

#### Locations

- **Add JARs and Folders**: This button allows you to add new JAR files or folders to your configuration.
- **Remove Selected Locations**: This button will remove the currently selected locations from your configuration.
- **Ordering Buttons**: Adjust the priority order of locations, affecting which classes are imported when duplicates exist.

#### Rules

Rules in the Code Explorer mode are used to specify allowed and forbidden dependencies, among other settings. Rules are defined in the following formats:

```
[command] [originPattern] [direction] [targetPattern]
classpath [path]
ignore class [classPattern]
import interface [classPattern]
import annotation [classPattern].[methodName]()
group [classPattern]
group [classPattern] as [group name]
ignore group [classPattern]
```

- **Revert**: Undoes the last change made to the rule configuration.
- **Help**: Provides documentation related to creating and managing rules.

## Analysis Results

After running an analysis with the "Run Analysis" button, the result is represented as an interactive mind map that visualizes all packages and classes.

### Mind Map Structure

- **Packages and Classes**: Displayed in a hierarchical format, with packages expanding to reveal classes contained within them.
- **Dependencies**: Represented as connectors between nodes on the mind map.
- **Forbidden Dependencies**: Illustrated with red lines, these dependencies are configured in the rules to be disallowed.

### Dependencies Tab

![Dependencies](../images/dependencies.png)

The Dependencies tab dynamically updates with information as the selection within the mind map changes. It provides a detailed list of dependencies including verdict, origin, target, and the specific details about the nature of the dependency.

#### Filtering Dependencies

- The filter input field allows users to filter the list of dependencies by entering keywords or by specifying a column for searching using the format `column:keyword`.

## Special Filters and Exploration Tools

### Toolbar Filters

The toolbar provides a set of actions for quick application of special filters related to dependency analysis. They can be used in combinations with the general filter toolbar and filter menu.

### Explore Menu Options

The "Explore" menu encompasses all the actions available on the toolbar for filtering dependencies, as well as additional actions for more advanced analysis.
2 changes: 2 additions & 0 deletions src/docs/user-documentation/user-documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,5 @@
- [Relationship to FreeMind](Relationship_to_FreeMind.md)
- [References to other known documentation/tutorial sites](other-docs-tutorials.md)
- [Mind map examples](https://github.com/freeplane/freeplane/discussions/categories/shared-mind-maps)
- [Code explorer](Code_Explorer.md)
- [ArchUnit Test Result Viewer](ArchUnit_Extension.md)

0 comments on commit ebce018

Please sign in to comment.