Microsoft/alguidelines
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add comprehensive agentic coding documentation

Browse source 
- Add 6 MCP server documentation pages (bc-code-intelligence, al-dependency, azure-devops, serena, al-objid, clockify)
- Add AI Coding Agents documentation (GitHub Copilot, Claude, Cursor)
- Add Getting Started section (what is agentic coding, setup, prompting, best practices, limitations, glossary)
- Add Getting More section (code review, documentation, telemetry examples)
- Add Community Resources placeholders (articles, videos, tools)
- Update Tools section to focus on MCP servers instead of VSCode extensions
This commit is contained in:
Jeremy Vyska 2025-10-10 12:25:41 +02:00
parent 3254d9b7e8
commit 4db38ba4d3
28 changed files with 8152 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

661
content/docs/agentic-coding/GettingMore/documentation.md Normal file
View file

@ -0,0 +1,661 @@
---
title: "Generating Documentation"
linkTitle: "Documentation"
weight: 2
description: >
Use AI to create and maintain comprehensive documentation for your AL code
---
## 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**:
```al
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**:
```al
/// <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**:
```markdown
# 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
```al
codeunit 50100 "Customer Email Manager"
{
procedure SendWelcomeEmail(CustomerNo: Code[20]): Boolean
}
```
**Example:**
```al
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](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.
## Support
For issues and questions:
- Create an issue in our [GitHub repository](https://github.com/yourorg/customer-engagement)
- Email: support@yourcompany.com
## Changelog
See [CHANGELOG.md](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:**
| Name | Type | Description |
|------|------|-------------|
| CustomerNo | Code[20] | The unique identifier of the customer |
**Returns:**
| Type | Description |
|------|-------------|
| Boolean | `true` if email sent successfully, `false` otherwise |
**Example:**
```al
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:
```al
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](../telemetry)
- Explore [refactoring legacy code](../refactoring) while maintaining documentation
- See how to conduct [AI-assisted code reviews](../code-review)