diegosouzapw Code Examples Template Generator
Generate effective code examples for documentation.
Example Principles
The Three Types
| Type | Purpose | Length | Use When |
|---|---|---|---|
| Minimal | Show single concept | 5-10 lines | Teaching one thing |
| Complete | Show full usage | 20-50 lines | Production reference |
| Progressive | Build complexity | 3+ examples | Tutorial style |
Example Templates
Minimal Example
<?php
use Vendor\Package\Client;
$client = new Client();
$result = $client->process('data');
echo $result->status; // "success"
Characteristics:
- Single concept
- No error handling
- Shows expected output
- Copy-paste ready
Complete Example
<?php
declare(strict_types=1);
require 'vendor/autoload.php';
use Vendor\Package\Client;
use Vendor\Package\Config;
use Vendor\Package\Exception\ClientException;
// Configuration
$config = new Config(
apiKey: getenv('API_KEY') ?: throw new RuntimeException('API_KEY required'),
timeout: 30,
retries: 3,
);
// Initialize client
$client = new Client($config);
try {
// Make request
$result = $client->process([
'data' => 'input value',
'options' => ['validate' => true],
]);
// Handle success
echo "Status: {$result->status}\n";
echo "ID: {$result->id}\n";
} catch (ClientException $e) {
// Handle error
echo "Error: {$e->getMessage()}\n";
exit(1);
}
/* Output:
Status: success
ID: res_abc123
*/
Characteristics:
- Full imports
- Error handling
- Configuration
- Comments for sections
- Expected output
Progressive Example
## Basic Usage
Start with the simplest case:
```php
$client = new Client();
$result = $client->ping();
// "pong"
With Configuration
Add configuration options:
$client = new Client([
'timeout' => 30,
]);
$result = $client->ping();
// "pong"
With Authentication
Add authentication:
$client = new Client([
'api_key' => 'your-key',
'timeout' => 30,
]);
$result = $client->process('data');
// {"status": "success", "id": "..."}
Production Ready
Full example with error handling:
try {
$client = new Client([
'api_key' => getenv('API_KEY'),
'timeout' => 30,
'retries' => 3,
]);
$result = $client->process('data');
echo $result->status;
} catch (ClientException $e) {
error_log($e->getMessage());
exit(1);
}
## Example Patterns
### Before/After Pattern
```markdown
### Refactoring Example
**Before (Anti-pattern):**
```php
// ❌ Don't do this
$data = file_get_contents('data.json');
$json = json_decode($data);
if ($json === null) {
die('Invalid JSON');
}
After (Recommended):
// ✅ Do this instead
use Vendor\Package\JsonLoader;
$loader = new JsonLoader();
$data = $loader->load('data.json');
// Throws JsonException on invalid data
### Input/Output Pattern
```markdown
### String Transformation
**Input:**
```php
$input = "Hello World";
Code:
$result = $transformer->slugify($input);
Output:
$result = "hello-world";
### Comparison Pattern
```markdown
### Framework Comparison
**Symfony:**
```php
use Symfony\Component\HttpFoundation\Response;
return new Response('Hello', 200);
Laravel:
return response('Hello', 200);
Native:
http_response_code(200);
echo 'Hello';
## Code Block Guidelines
### Language Tags
```markdown
```php # PHP code
```bash # Shell commands
```json # JSON data
```yaml # YAML config
```sql # Database queries
```diff # Code changes
Highlighting Important Parts
<?php
$client = new Client([
// highlight-next-line
'api_key' => 'your-key', // <-- This is important
'timeout' => 30,
]);
Showing Line Numbers
```php {1,3-5}
<?php // Line 1
// Line 2
$config = new Config(); // Line 3
$config->setTimeout(30); // Line 4
$config->setRetries(3); // Line 5
## Common Patterns
### CRUD Operations
```markdown
### Create
```php
$item = $client->items->create([
'name' => 'New Item',
'price' => 99.99,
]);
echo $item->id; // "item_abc123"
Read
$item = $client->items->get('item_abc123');
echo $item->name; // "New Item"
Update
$item = $client->items->update('item_abc123', [
'price' => 79.99,
]);
echo $item->price; // 79.99
Delete
$client->items->delete('item_abc123');
// No return value, throws on error
List
$items = $client->items->list(['limit' => 10]);
foreach ($items as $item) {
echo "{$item->name}: {$item->price}\n";
}
### Error Handling
```markdown
### Handling Errors
```php
use Vendor\Package\Exception\{
NotFoundException,
ValidationException,
RateLimitException,
};
try {
$result = $client->process($data);
} catch (NotFoundException $e) {
// Resource doesn't exist
echo "Not found: {$e->getMessage()}";
} catch (ValidationException $e) {
// Invalid input
foreach ($e->getErrors() as $field => $messages) {
echo "{$field}: " . implode(', ', $messages) . "\n";
}
} catch (RateLimitException $e) {
// Too many requests
sleep($e->getRetryAfter());
// Retry...
}
### Async Operations
```markdown
### Async Processing
```php
// Start async job
$job = $client->jobs->create([
'type' => 'export',
'params' => ['format' => 'csv'],
]);
echo "Job started: {$job->id}\n";
// Poll for completion
while ($job->status !== 'completed') {
sleep(5);
$job = $client->jobs->get($job->id);
echo "Status: {$job->status}\n";
}
// Get result
$result = $client->jobs->getResult($job->id);
file_put_contents('export.csv', $result->content);
## Quality Checklist
### Every Example Should
- [ ] Run without modification (except config)
- [ ] Show expected output
- [ ] Use realistic data (not foo/bar)
- [ ] Include necessary imports
- [ ] Follow PSR-12 style
- [ ] Match current API version
### Avoid
- [ ] Abstract examples that don't run
- [ ] Missing `<?php` tag when standalone
- [ ] Outdated syntax or deprecated methods
- [ ] Foo/Bar/Baz placeholder names
- [ ] Missing required configuration
- [ ] Unexplained magic values
## Generation Instructions
When generating code examples:
1. **Choose example type** based on purpose
2. **Use realistic data** (emails, names, prices)
3. **Include expected output** in comments
4. **Show imports** when needed
5. **Add error handling** in complete examples
6. **Test examples** actually run
7. **Match coding style** of the project