AI-Powered Code Explanations Documentation

Revolutionary AI-generated documentation that combines engaging narrative with multiple UML diagrams - creating rich, visual explanations that read like a well-crafted technical article.

Table of Contents

• Overview
• Three Explanation Modes
• AI Configuration
• PlantUML Repair Feature
• Custom Markdown
• Export Features
• Best Practices

Overview

GitUML's AI-Powered Explanations feature goes beyond simple code documentation. Instead of providing isolated diagrams or dry text descriptions, the AI creates comprehensive technical narratives that seamlessly blend prose with strategically placed UML diagrams.

Think of it as having an expert technical writer who deeply understands UML, software architecture, and visual communication working on your documentation.

What Makes AI Explanations Special?

• Multi-Diagram Support: Class, sequence, state, activity, component, use case, and ER diagrams
• Intelligent Placement: Diagrams appear exactly where they enhance understanding
• Engaging Narratives: Documentation that reads like a well-written technical article
• Editable Output: Full control over the generated content with custom markdown support
• Export Ready: PDF and HTML export with embedded diagrams

Three Explanation Modes

GitUML offers three flexible ways to generate AI-powered explanations, each suited to different workflows and use cases.

1. GitHub Repository Mode

The most powerful mode for documenting complete projects or specific modules within a codebase.

How It Works:

1. Navigate to Explanations → New Explanation from GitHub
2. Enter the GitHub repository URL (public or private)
3. Browse the repository structure and select the files you want explained
4. Configure AI settings (model, provider, custom instructions)
5. Click Generate Explanation

Best For:

• Documenting entire modules or subsystems
• Creating onboarding documentation for new team members
• Understanding open-source projects
• Generating architecture documentation

Features:

• Access to both public and private repositories (with authentication)
• Full directory browsing with file selection
• Automatic language detection
• Context-aware analysis across multiple files

2. File Upload Mode

Perfect for code that isn't in version control yet or when you want to document specific files from your local machine.

How It Works:

1. Navigate to Explanations → New Explanation from Upload
2. Upload one or multiple source code files (drag and drop supported)
3. Review the uploaded files and configure AI settings
4. Click Generate Explanation

Best For:

• Private codebases not on GitHub
• Work-in-progress code
• Code samples for documentation
• Legacy code analysis

Supported Languages:

Python (.py), Java (.java), JavaScript (.js), TypeScript (.ts, .tsx), C# (.cs), Objective-C (.m, .h), Delphi/Pascal (.pas), Vue (.vue), JSX (.jsx), and HTML with embedded scripts.

3. Code Snippet Mode

The fastest way to get explanations for algorithms, patterns, or small code fragments.

How It Works:

1. Navigate to Explanations → New Explanation from Snippet
2. Paste your code directly into the editor
3. Optionally specify the programming language (auto-detected if not specified)
4. Configure AI settings
5. Click Generate Explanation

Best For:

• Explaining specific algorithms or functions
• Documenting design patterns
• Quick code reviews
• Learning from code examples
• Stack Overflow answers with visual documentation

Features:

• Syntax highlighting in the editor
• Automatic language detection
• No file upload required
• Instant results

AI Configuration

GitUML gives you complete control over how AI explanations are generated through the AI Configuration panel available in all explanation modes.

AI Service Providers

GitUML supports multiple AI providers through a Bring Your Own Key (BYOK) system for PRO users:

Supported Providers:

• OpenAI - GPT-4, GPT-4 Turbo, GPT-5 (when available)
  • Best for: General-purpose explanations, balanced quality and speed
  • API Key required: Get from OpenAI Platform
• Anthropic - Claude 3.5 Sonnet, Claude 3 Opus, Claude 4.5 (latest)
  • Best for: Detailed technical writing, complex code analysis
  • API Key required: Get from Anthropic Console
• Google - Gemini 2.5 Pro, Gemini 2.5 Flash
  • Best for: Large context windows, comprehensive explanations
  • API Key required: Get from Google AI Studio
• Ollama Cloud - Various open-source models
  • Best for: Privacy-conscious users, cost control
  • API Key required: Get from Ollama
• Together.ai - Open-source model marketplace
  • Best for: Experimenting with different models, cost efficiency
  • API Key required: Get from Together.ai
• Grok - X's AI models
  • Best for: Alternative to mainstream providers
  • API Key required: Get from X.AI

Configuring AI Settings

The AI Configuration panel allows you to customize:

• AI Provider: Choose from supported providers
• Model: Select specific model version (e.g., GPT-4, Claude 3.5 Sonnet)
• API Key: Enter your API key (PRO users only, securely stored)
• Temperature: Control creativity (0.0 = focused, 1.0 = creative)
• Max Tokens: Set maximum response length
• Custom Instructions: Add specific guidance for the AI

Custom Instructions Examples:

• "Focus on security vulnerabilities and potential improvements"
• "Explain this as if teaching to junior developers"
• "Emphasize design patterns and architectural decisions"
• "Include performance considerations for each component"
• "Generate more sequence diagrams than class diagrams"

Model Selection Guide

Use Case	Recommended Model	Why
Quick explanations	GPT-4 Turbo, Gemini Flash	Fast response, good quality
Detailed documentation	Claude 3.5 Sonnet, GPT-4	Superior writing quality
Large codebases	Gemini 2.5 Pro	Huge context window
Cost-conscious	Together.ai models	Open-source, lower cost
Privacy-critical	Ollama (self-hosted)	Complete data control

PlantUML Repair Feature

One of the most powerful features of GitUML's AI Explanations is the PlantUML Repair capability. AI-generated PlantUML diagrams sometimes contain syntax errors or malformed markup. The repair feature automatically fixes these issues.

What PlantUML Repair Does

• Detects syntax errors in AI-generated PlantUML markup
• Automatically fixes common issues:
  • Missing or mismatched braces
  • Incorrect relationship syntax
  • Invalid PlantUML keywords
  • Malformed class/method definitions
• Preserves the original intent of the diagram
• Generates working PlantUML that renders correctly

When to Use PlantUML Repair

The repair feature runs automatically in the background, but you can manually trigger it when:

• Generated diagrams fail to render
• PlantUML syntax errors appear in the explanation
• You've manually edited PlantUML and want to validate it
• You want to optimize diagram layout

How It Works

1. AI generates explanation with PlantUML diagrams
2. GitUML attempts to render each diagram
3. If rendering fails, the repair system:
   • Analyzes the error
   • Sends the malformed PlantUML to an AI model for correction
   • Validates the repaired PlantUML
   • Updates the explanation with working markup
4. You see the corrected, rendered diagram

Manual PlantUML Repair

In the explanation editor, you can manually trigger PlantUML repair:

1. Locate the diagram with issues in the Custom Markdown section
2. Click the Repair PlantUML button
3. Review the suggested fixes
4. Apply or modify as needed

Custom Markdown

Custom Markdown is where GitUML's AI Explanations truly shine. You have complete control over the generated content and can blend AI-generated explanations with your own narrative and diagrams.

Two Custom Markdown Areas

Every explanation has two custom markdown sections:

• Custom Markdown Before Main: Content that appears before the AI-generated explanation
• Custom Markdown After Main: Content that appears after the AI-generated explanation

What You Can Add

1. Rich Text Narrative

Add your own explanations, context, or commentary using full Markdown syntax:

• Headings, lists, tables
• Bold, italic, code formatting
• Links, images
• Blockquotes, horizontal rules

2. PlantUML Diagrams from GitUML's Diagram Generator

This is a game-changer: You can take PlantUML markup generated by GitUML's traditional UML diagram generator and paste it into the custom markdown areas!

The Best of Both Worlds:

1. Use GitUML's Diagram Generator to create precise class diagrams from your codebase through proper parsing
   • Navigate to New Diagram → From GitHub Repo
   • Select files and generate a UML class diagram
   • Copy the PlantUML markup from the diagram editor
2. Create an AI Explanation for the same code
   • Navigate to Explanations → New Explanation from GitHub
   • Select the same files
   • Generate the AI explanation
3. Combine Them in Custom Markdown
   • Paste the GitUML-generated PlantUML into "Custom Markdown Before Main"
   • Now you have: precise class diagrams (from parsing) + engaging AI narrative + AI-generated sequence/state diagrams

Custom Markdown Examples

Example 1: Adding Context Before AI Explanation

## Project Overview

This module implements the authentication system for our application.
It follows the OAuth 2.0 specification with custom extensions for
multi-tenant support.

### Key Design Decisions

1. **Token Storage**: Redis for session tokens, PostgreSQL for refresh tokens
2. **Security**: All tokens are encrypted at rest using AES-256
3. **Performance**: Token validation is cached for 5 minutes

The following AI-generated explanation provides detailed insights into
the implementation...

Example 2: Adding GitUML Class Diagram

## Precise Class Structure

The following diagram was generated by GitUML's parser and shows the
exact class relationships as they exist in the code:

```plantuml
@startuml
class AuthenticationService {
  - tokenStore: TokenStore
  - userRepository: UserRepository
  + authenticate(credentials: Credentials): Token
  + validateToken(token: string): User
}

class TokenStore {
  + store(token: Token): void
  + retrieve(tokenId: string): Token
  + invalidate(tokenId: string): void
}

AuthenticationService --> TokenStore
AuthenticationService --> UserRepository
@enduml
```

Now let's dive into how these components work together...

Example 3: Adding Follow-Up Content After AI Explanation

## Additional Resources

- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
- [Internal Wiki: Authentication Best Practices](https://wiki.company.com/auth)
- [API Documentation](https://api.company.com/docs/auth)

## Next Steps

After understanding this authentication module, explore:

1. **Authorization Module** - How permissions are enforced
2. **User Management** - CRUD operations for user accounts
3. **Audit Logging** - Tracking authentication events

Editing Custom Markdown

Custom Markdown sections are fully editable in the explanation editor:

1. Navigate to your explanation
2. Scroll to the "Custom Markdown Before Main" or "Custom Markdown After Main" panels
3. Click to expand (if collapsed)
4. Edit using Markdown syntax
5. Save your changes
6. Preview to see the rendered result

Export Features

Once you've created your AI-powered explanation (with or without custom markdown), you can export it in multiple formats for sharing, archiving, or offline viewing.

Export Formats

1. PDF Export

Create professional, print-ready PDF documents with embedded diagrams.

• High-quality rendering: All diagrams are embedded as vector graphics
• Custom styling: Professional typography and layout
• Table of contents: Automatically generated from headings
• Pagination: Proper page breaks and numbering
• Hyperlinks: Internal and external links preserved

Best for: Documentation archives, presentations, handouts, formal documentation

2. HTML Export

Export as a standalone HTML file that can be viewed in any browser.

• Self-contained: All diagrams embedded as inline SVG or base64 images
• Responsive: Adapts to different screen sizes
• Interactive: Diagrams can be zoomed and panned
• No dependencies: Works offline without external resources
• Styled: Clean, readable layout with syntax highlighting

Best for: Internal wikis, blog posts, email attachments, offline viewing

3. Markdown Export

Export the raw Markdown with PlantUML code blocks.

• Portable: Plain text format
• Editable: Easy to modify in any text editor
• Version control friendly: Works great with Git
• Tool-agnostic: Can be rendered by any Markdown processor

Best for: GitHub/GitLab documentation, version control, further editing

How to Export

1. Open the explanation you want to export
2. Click the Export button in the toolbar
3. Choose your desired format (PDF, HTML, or Markdown)
4. Configure export options (if available):
   • Include/exclude table of contents
   • Page size (PDF only)
   • Diagram format (SVG vs PNG)
5. Click Download

Export Options

PDF Export Options

• Page Size: A4, Letter, Legal
• Orientation: Portrait or Landscape
• Margins: Normal, Narrow, Wide
• Header/Footer: Include page numbers, title, date
• Table of Contents: Enable/disable, depth level

HTML Export Options

• Theme: Light or Dark
• Diagram Format: SVG (crisp, zoomable) or PNG (compatible)
• Include Source: Option to include raw Markdown as comments
• Syntax Highlighting: Choose color scheme

Bulk Export

PRO users can export multiple explanations at once:

1. Navigate to your Explanations List
2. Select multiple explanations using checkboxes
3. Click Bulk Actions → Export
4. Choose format and options
5. Download as a ZIP file

Best Practices

Creating Effective Explanations

• Be Selective: Don't include every file. Focus on the core logic
• Provide Context: Use custom markdown to add project-specific context
• Iterate: Generate, review, and regenerate with refined instructions
• Mix Approaches: Combine parser-generated diagrams with AI explanations
• Use Custom Instructions: Guide the AI to focus on what matters most

Optimizing AI Configuration

• Start with defaults: Default settings work well for most cases
• Adjust temperature: Lower (0.3-0.5) for technical accuracy, higher (0.7-0.9) for creativity
• Set appropriate max tokens: Longer code needs more tokens
• Try different models: Each model has strengths - experiment to find the best fit

Working with Custom Markdown

• Before Main: Use for overviews, prerequisites, architectural context
• After Main: Use for follow-up resources, related topics, next steps
• Embed GitUML diagrams: Add precise class diagrams from the parser
• Keep it organized: Use clear headings and hierarchical structure

Export Best Practices

• PDF for archival: Use when documentation needs to be preserved long-term
• HTML for sharing: Best for quick sharing via email or web
• Markdown for collaboration: Great for team editing and version control
• Test exports: Always preview before sharing

Performance Tips

• Limit file count: 10-20 files per explanation for best results
• Break up large projects: Create multiple explanations for different modules
• Use snippet mode for quick tests: Test instructions on small code samples first
• Cache and reuse: Save explanations and update them rather than regenerating

Getting Help

Need assistance? Here's how to get help:

• Documentation: Review this page and the Blog/FAQ
• Examples: Browse public explanations for inspiration
• Support: Contact us at abulka@gmail.com
• Community: Share tips and tricks in the GitUML community

---

Last updated: October 2025 | Back to Home | Blog/FAQ