Generating Documentation

Scenario

You have a well-functioning AL extension but it lacks documentation. You need to create:

• XML documentation comments for all procedures
• A comprehensive README file
• API documentation for public interfaces
• User-facing feature documentation

Goal

Use AI to quickly generate high-quality documentation that:

• Explains what the code does
• Documents parameters and return values
• Provides usage examples
• Helps developers and users understand the extension

Types of Documentation

1. XML Documentation Comments

In-code documentation for procedures, triggers, and events.

2. README Files

Project overview, setup instructions, and getting started guides.

3. API Documentation

Documentation for public APIs and integration points.

4. User Documentation

End-user guides and feature explanations.

Step-by-Step Guide

Step 1: XML Documentation for Procedures

Scenario: You have a codeunit without documentation.

Starting Code:

codeunit 50100 "Customer Email Manager"
{
    procedure SendWelcomeEmail(CustomerNo: Code[20]): Boolean
    var
        Customer: Record Customer;
        EmailMessage: Codeunit "Email Message";
    begin
        if not Customer.Get(CustomerNo) then
            exit(false);

        if Customer."E-Mail" = '' then
            exit(false);

        EmailMessage.Create(Customer."E-Mail", 'Welcome!', GetWelcomeEmailBody(Customer));
        exit(EmailMessage.Send());
    end;

    local procedure GetWelcomeEmailBody(Customer: Record Customer): Text
    begin
        exit(StrSubstNo('Dear %1, welcome to our service!', Customer.Name));
    end;
}

Prompt:

Add XML documentation comments to all procedures in this codeunit.
Include:
- Summary for each procedure
- Parameter descriptions
- Return value descriptions
- Example usage where helpful
- Any important notes or warnings

[Paste the code]

Expected Result:

/// <summary>
/// Manages customer email communications
/// </summary>
codeunit 50100 "Customer Email Manager"
{
    /// <summary>
    /// Sends a welcome email to a customer
    /// </summary>
    /// <param name="CustomerNo">The customer number to send the email to</param>
    /// <returns>True if the email was sent successfully, false otherwise</returns>
    /// <remarks>
    /// The procedure will return false if:
    /// - The customer does not exist
    /// - The customer has no email address
    /// - The email fails to send
    /// </remarks>
    /// <example>
    /// if CustomerEmailManager.SendWelcomeEmail('C001') then
    ///     Message('Welcome email sent successfully');
    /// </example>
    procedure SendWelcomeEmail(CustomerNo: Code[20]): Boolean
    var
        Customer: Record Customer;
        EmailMessage: Codeunit "Email Message";
    begin
        if not Customer.Get(CustomerNo) then
            exit(false);

        if Customer."E-Mail" = '' then
            exit(false);

        EmailMessage.Create(Customer."E-Mail", 'Welcome!', GetWelcomeEmailBody(Customer));
        exit(EmailMessage.Send());
    end;

    /// <summary>
    /// Generates the body text for the welcome email
    /// </summary>
    /// <param name="Customer">The customer record to generate the email for</param>
    /// <returns>The formatted email body text</returns>
    local procedure GetWelcomeEmailBody(Customer: Record Customer): Text
    begin
        exit(StrSubstNo('Dear %1, welcome to our service!', Customer.Name));
    end;
}

Step 2: Batch Documentation for Multiple Files

Prompt:

I have multiple AL files that need XML documentation.
For each public procedure, add:
- Summary
- Parameter descriptions  
- Return value (if applicable)
- Example usage

Process these files:
[List files or paste multiple code blocks]

Tip: Do this in batches of 3-5 files to maintain context and quality.

Step 3: Creating a README File

Prompt:

Create a comprehensive README.md for my AL extension with the following information:

Extension Name: Customer Engagement Suite
Purpose: Enhance customer communication and engagement features
Key Features:
- Automated welcome emails
- Customer portal access
- Newsletter subscription management
- Customer satisfaction surveys

Include sections for:
- Overview and purpose
- Features list
- Installation instructions
- Configuration steps
- Usage examples
- Dependencies
- Compatibility (BC version 21+)
- Contributing guidelines
- License (MIT)

Expected Structure:

# Customer Engagement Suite

> Enhance customer communication and engagement in Microsoft Dynamics 365 Business Central

## Overview

The Customer Engagement Suite is a Business Central extension that provides comprehensive 
tools for managing customer communications and engagement activities.

## Features

### Automated Welcome Emails
Automatically send personalized welcome emails to new customers upon registration.

### Customer Portal Access
Enable customers to access a self-service portal for order tracking and account management.

### Newsletter Subscription Management
Allow customers to manage their newsletter preferences and subscriptions.

### Customer Satisfaction Surveys
Collect and analyze customer feedback through integrated surveys.

## Installation

### Prerequisites
- Microsoft Dynamics 365 Business Central version 21.0 or higher
- Email account configured in Business Central
- System Application extension installed

### Steps

1. Download the extension file (.app)
2. Open Business Central Administration Shell
3. Run the installation command:
   ```powershell
   Publish-NAVApp -ServerInstance BC210 -Path "CustomerEngagementSuite.app"
   Install-NAVApp -ServerInstance BC210 -Name "Customer Engagement Suite"

Configuration

Email Setup

1. Navigate to Email Accounts page
2. Configure your SMTP settings
3. Test the email connection

Welcome Email Template

1. Go to Customer Engagement Setup
2. Configure the welcome email template
3. Enable automatic sending

Usage

Sending Welcome Emails

codeunit 50100 "Customer Email Manager"
{
    procedure SendWelcomeEmail(CustomerNo: Code[20]): Boolean
}

Example:

CustomerEmailManager: Codeunit "Customer Email Manager";
begin
    if CustomerEmailManager.SendWelcomeEmail('C001') then
        Message('Welcome email sent successfully');
end;

Dependencies

• System Application: Core BC functionality
• Base Application: Standard BC tables and pages

Compatibility

• Business Central: Version 21.0 and higher
• Platform: Compatible with both SaaS and On-Premises

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue in our GitHub repository
• Email: support@yourcompany.com

Changelog

See CHANGELOG.md for version history.

### Step 4: API Documentation

**Prompt**:

Create API documentation for the public procedures in my Customer Email Manager codeunit. Format it as markdown suitable for a developer portal.

Include:

• Procedure signature
• Description
• Parameters with types and descriptions
• Return values
• Code examples
• Error conditions
• Notes and best practices

[Include the codeunit code]

**Expected Output**:
```markdown
# Customer Email Manager API

## Overview
The Customer Email Manager provides functionality for sending customer-related emails.

## Procedures

### SendWelcomeEmail

Sends a welcome email to a specified customer.

**Signature:**
```al
procedure SendWelcomeEmail(CustomerNo: Code[20]): Boolean

Parameters:

Returns:

Example:

var
    CustomerEmailManager: Codeunit "Customer Email Manager";
    Success: Boolean;
begin
    Success := CustomerEmailManager.SendWelcomeEmail('C00001');
    if Success then
        Message('Email sent successfully')
    else
        Error('Failed to send email');
end;

Error Conditions:

The procedure returns false in the following cases:

• Customer does not exist
• Customer has no email address configured
• Email service is unavailable

Best Practices:

• Always check the return value
• Ensure email account is configured before calling
• Consider calling asynchronously for better performance

See Also:

• Email Account Setup
• Customer Configuration

### Step 5: User Documentation

**Prompt**:

Create user-facing documentation for the Welcome Email feature. Target audience: Business users who are not developers.

Explain:

• What the feature does
• How to enable/configure it
• How to use it
• Troubleshooting common issues

Use simple language and include screenshots placeholders where helpful.

**Expected Output**:
```markdown
# Welcome Email Feature

## What is the Welcome Email Feature?

The Welcome Email feature automatically sends a personalized email to new customers 
when they are added to your system. This helps create a positive first impression 
and provides important information to your customers right away.

## Enabling Welcome Emails

1. Open Business Central
2. Search for "Customer Engagement Setup"
3. Check the box next to "Send Welcome Emails"
4. Click "OK" to save

![Setup Screenshot]

## Configuring the Email Template

### Step 1: Access Email Templates
1. Search for "Email Templates"
2. Find "Customer Welcome Email"
3. Click "Edit"

### Step 2: Customize the Message
1. Update the email subject line
2. Modify the email body
3. Add your company logo
4. Click "OK" to save

### Step 3: Test the Email
1. Open a test customer
2. Click "Actions" > "Send Welcome Email"
3. Check that you receive the email

## Using Welcome Emails

### Automatic Sending
When enabled, welcome emails are sent automatically when:
- A new customer is created
- An existing customer is marked as active for the first time

### Manual Sending
You can also send welcome emails manually:

1. Open the customer card
2. Click "Actions" > "Email" > "Send Welcome Email"
3. Confirm the action

## Troubleshooting

### Email Not Sending

**Problem:** Welcome emails are not being sent

**Solutions:**
- Check that the feature is enabled in setup
- Verify the customer has an email address
- Confirm your email account is configured correctly
- Check that email service is running

### Wrong Email Template

**Problem:** Customers receive the wrong email content

**Solutions:**
- Review the email template configuration
- Ensure you're editing the correct template
- Clear any cached templates

### Customer Not Receiving Email

**Problem:** Email shows as sent but customer didn't receive it

**Solutions:**
- Ask customer to check spam folder
- Verify the email address is correct
- Check email delivery logs
- Test with a different email address

## Tips and Best Practices

- **Personalization**: Use customer name and company name in the email
- **Timing**: Send welcome emails within 24 hours of customer creation
- **Follow-up**: Consider a follow-up email series
- **Feedback**: Ask customers if they received and found the email helpful

## Need Help?

Contact your Business Central administrator or support team for assistance.

Review Points

After generating documentation, verify:

✅ Accuracy

• Documentation matches actual code behavior
• Parameter descriptions are correct
• Return values accurately described
• Examples work as shown

✅ Completeness

• All public procedures documented
• All parameters explained
• Edge cases mentioned
• Error conditions documented

✅ Clarity

• Easy to understand
• Appropriate level of detail
• Good examples provided
• Proper formatting

✅ Maintenance

• Easy to update
• Versioned appropriately
• Consistent style
• Well organized

Advanced Documentation Prompts

Generate CHANGELOG

Create a CHANGELOG.md file documenting these changes from version 1.0 to 2.0:
- Added: Customer portal access
- Added: Newsletter preferences
- Changed: Welcome email now includes portal link
- Fixed: Email encoding issues with special characters
- Deprecated: Old email API (will be removed in 3.0)

Follow Keep a Changelog format.

Create Migration Guide

Create a migration guide for users upgrading from version 1.x to 2.0.
Include:
- Breaking changes
- New features
- Configuration changes needed
- Data migration steps
- Deprecation warnings

Generate Inline Code Comments

Add helpful inline comments to this complex procedure explaining the logic flow.
Don't over-comment obvious code, but do explain:
- Complex algorithms
- Business rule implementations
- Non-obvious optimizations
- Workarounds

[Paste code]

Keeping Documentation Updated

When Code Changes

Prompt:

I've updated this procedure to add a new parameter.
Update the XML documentation to reflect the change:

Old procedure:
[paste old code]

New procedure:
[paste new code]

Regular Documentation Reviews

Prompt:

Review the documentation for this codeunit.
Check for:
- Outdated information
- Missing documentation
- Incorrect examples
- Deprecated features

[Paste codeunit]

Best Practices

1. Document As You Code

I'm about to write a procedure to validate customer credit limits.
Create the XML documentation comment first, then we'll implement the procedure.

2. Use Consistent Style

Create a documentation template:

Create an XML documentation template I can use for all my procedures.
Include sections for: summary, parameters, returns, exceptions, examples, and remarks.

3. Generate Documentation in Batches

Document related code together for consistency:

Document all procedures in this codeunit that relate to email sending.
Use consistent terminology and structure.

4. Include Real Examples

Add a realistic code example to this procedure's documentation showing:
- Typical usage
- Error handling
- Integration with other features

Common Documentation Patterns

For Validation Procedures

Document this validation procedure. Include:
- What is being validated
- Valid conditions
- Error messages that can be raised
- Example of valid and invalid inputs

For Event Subscribers

Document this event subscriber. Include:
- What event it subscribes to
- When it triggers
- What it does
- Side effects or implications
- Integration points

For APIs

Create REST API documentation for this AL API page.
Include:
- Endpoint URL
- HTTP methods supported
- Request/response examples
- Authentication requirements
- Error codes

Practice Exercise

Generate documentation for this code:

codeunit 50110 "Order Status Manager"
{
    procedure UpdateOrderStatus(OrderNo: Code[20]; NewStatus: Enum "Order Status"): Boolean
    var
        SalesHeader: Record "Sales Header";
    begin
        if not SalesHeader.Get(SalesHeader."Document Type"::Order, OrderNo) then
            exit(false);

        SalesHeader.Status := NewStatus;
        SalesHeader.Modify(true);
        SendStatusNotification(OrderNo, NewStatus);
        exit(true);
    end;

    local procedure SendStatusNotification(OrderNo: Code[20]; Status: Enum "Order Status")
    begin
        // Implementation
    end;
}

Your Tasks:

1. Generate XML documentation
2. Create a README section explaining this feature
3. Write API documentation
4. Create user documentation
5. Review and improve the generated docs

Next Steps

• Learn how to use AI for adding telemetry
• Explore refactoring legacy code while maintaining documentation
• See how to conduct AI-assisted code reviews