Getting Started

Minimal Setup

Installation

composer require irazasyed/docgen

Publish the config file (if needed):

php artisan vendor:publish --provider="Irazasyed\Docgen\DocgenServiceProvider"

Basic Usage

Ensure your package has a Facade class (e.g., YourPackageFacade).

Annotate your facade methods with PHPDoc blocks:

/**
 * @param string $param Description of the parameter.
 * @return mixed Description of the return value.
 */
public static function exampleMethod($param) { ... }

Run the generator:
```
php artisan docgen:generate
```
Output will be saved to resources/docs/ (configurable).

First Use Case Generate a Markdown file for your facade’s API to include in your package’s README.md or documentation.

Implementation Patterns

Workflows

Integrating with CI/CD Add the generation step to your CI pipeline (e.g., GitHub Actions):
```
- name: Generate Docs
  run: php artisan docgen:generate
```
Commit the generated files to your repo (or store them in a separate branch).
Customizing Output Override the default template by publishing the views:
```
php artisan vendor:publish --tag="docgen-views"
```
Modify resources/views/docgen/markdown.blade.php to fit your branding.
Dynamic Documentation Use the --force flag to regenerate docs on every push:
```
php artisan docgen:generate --force
```
Facade-Only Packages For packages without a facade, extend the generator to support service classes by:
- Creating a custom command extending DocgenCommand.
- Overriding generate() to parse non-facade classes.

Integration Tips

Laravel Packages: Use config('docgen.path') to dynamically set output paths per environment.
Monorepos: Exclude unrelated packages from generation by filtering facades in config/docgen.php:
```
'facades' => [
    'YourPackage\\Facades\\*',
],
```

Markdown Integration: Embed docs in your README.md via:

<!-- AUTO-GENERATED-DOCS:START -->
@include 'docs/your-package.md'
<!-- AUTO-GENERATED-DOCS:END -->

Gotchas and Tips

Pitfalls

Facade Discovery
- Issue: Docgen only processes facades listed in config/docgen.php or auto-discovered via Facade::class.
- Fix: Manually specify facades in the config if auto-discovery fails:
```
'facades' => [
    'YourPackage\\Facades\\YourFacade',
],
```
PHPDoc Parsing
- Issue: Complex PHPDoc (e.g., @throws, @template) may break parsing.
- Fix: Simplify annotations or extend the parser via DocgenServiceProvider::boot():
```
$this->app->singleton('docgen.parser', function () {
    return new CustomParser();
});
```
Caching
- Issue: Generated files aren’t updated until --force is used.
- Fix: Clear the cache after changes:
```
php artisan cache:clear && php artisan docgen:generate
```
Namespace Conflicts
- Issue: Facades with similar names may cause collisions in output.
- Fix: Use unique aliases in PHPDoc @method tags:
```
/**
 * @method static string yourMethodAlias(string $param)
 */
```

Debugging

Log Parsing Errors: Enable debug mode in config/docgen.php:
```
'debug' => env('DOCGEN_DEBUG', false),
```

Validate Facades: Check if your facade extends Illuminate\Support\Facades\Facade:

use Illuminate\Support\Facades\Facade;
class YourFacade extends Facade { ... }

Extension Points

Custom Templates Override the default Markdown template by publishing views and extending DocgenServiceProvider:
```
public function boot()
{
    $this->loadViewsFrom(__DIR__.'/views', 'docgen');
}
```

Pre/Post-Generation Hooks Add logic before/after generation in a service provider:

Docgen::generating(function () {
    // Pre-generation logic
});

Docgen::generated(function ($output) {
    // Post-generation logic (e.g., upload to S3)
});

Non-Facade Classes Extend the generator to support services/controllers by:
- Creating a custom command:
```
php artisan make:command CustomDocgenCommand
```
- Parsing classes with ReflectionClass and integrating with Docgen’s output logic.

Docgen Laravel Package