@mytechtoday/augment-extensions 0.7.0 → 1.2.1

package/augment-extensions/domain-rules/wordpress-plugin/rules/documentation-standards.md

@@ -1,463 +1,463 @@
-# WordPress Plugin Documentation Standards
-
-## Overview
-
-This document defines documentation standards for WordPress plugins, covering inline code documentation (PHPDoc), readme.txt for WordPress.org, README.md for GitHub, and user-facing documentation.
-
----
-
-## PHPDoc Standards
-
-### File Headers
-
-Every PHP file must include a file-level DocBlock:
-
-```php
-<?php
-/**
- * Plugin Name: My Plugin
- * Description: Brief description
- * Version: 1.0.0
- * Author: Author Name
- * License: GPL-2.0+
- * Text Domain: my-plugin
- *
- * @package    My_Plugin
- * @subpackage My_Plugin/includes
- * @author     Author Name <email@example.com>
- * @license    GPL-2.0+ http://www.gnu.org/licenses/gpl-2.0.txt
- * @link       https://example.com
- * @since      1.0.0
- */
-```
-
-### Class Documentation
-
-```php
-/**
- * Main plugin class.
- *
- * Handles plugin initialization, loading dependencies, and defining hooks.
- *
- * @since      1.0.0
- * @package    My_Plugin
- * @subpackage My_Plugin/includes
- * @author     Author Name <email@example.com>
- */
-class My_Plugin {
-    
-    /**
-     * The unique identifier of this plugin.
-     *
-     * @since    1.0.0
-     * @access   protected
-     * @var      string    $plugin_name    The string used to uniquely identify this plugin.
-     */
-    protected $plugin_name;
-    
-    /**
-     * Initialize the plugin.
-     *
-     * Sets the plugin name and version, loads dependencies, defines locale,
-     * and sets up admin and public hooks.
-     *
-     * @since    1.0.0
-     */
-    public function __construct() {
-        // Constructor code
-    }
-}
-```
-
-### Function Documentation
-
-```php
-/**
- * Retrieve posts with custom meta query.
- *
- * @since    1.0.0
- * @param    array    $args    Query arguments.
- * @param    bool     $cache   Whether to use cached results. Default true.
- * @return   array|WP_Error    Array of posts or WP_Error on failure.
- */
-function my_plugin_get_posts( $args = array(), $cache = true ) {
-    // Function code
-}
-```
-
-### Hook Documentation
-
-```php
-/**
- * Fires after plugin initialization.
- *
- * @since 1.0.0
- * @param My_Plugin $plugin The main plugin instance.
- */
-do_action( 'my_plugin_initialized', $this );
-
-/**
- * Filters the plugin settings before saving.
- *
- * @since 1.0.0
- * @param array $settings The plugin settings array.
- * @param int   $user_id  The current user ID.
- */
-$settings = apply_filters( 'my_plugin_settings', $settings, get_current_user_id() );
-```
-
-### Required PHPDoc Tags
-
-- `@since` - Version when introduced (required for all)
-- `@param` - Parameter description (required for functions/methods with parameters)
-- `@return` - Return value description (required for functions/methods that return values)
-- `@access` - Access level (public, protected, private) for properties
-- `@var` - Variable type for properties
-- `@package` - Package name
-- `@author` - Author information
-- `@link` - Related URL
-- `@see` - Related function/class
-- `@deprecated` - Deprecation notice with version and alternative
-
----
-
-## readme.txt (WordPress.org)
-
-### Structure
-
-```
-=== Plugin Name ===
-Contributors: username1, username2
-Donate link: https://example.com/donate
-Tags: tag1, tag2, tag3
-Requires at least: 6.0
-Tested up to: 6.4
-Requires PHP: 7.4
-Stable tag: 1.0.0
-License: GPLv2 or later
-License URI: http://www.gnu.org/licenses/gpl-2.0.html
-
-Short description (max 150 characters).
-
-== Description ==
-
-Detailed description of the plugin.
-
-**Key Features:**
-
-* Feature 1
-* Feature 2
-* Feature 3
-
-**Use Cases:**
-
-* Use case 1
-* Use case 2
-
-== Installation ==
-
-1. Upload the plugin files to `/wp-content/plugins/my-plugin`
-2. Activate the plugin through the 'Plugins' menu
-3. Configure settings at Settings > My Plugin
-
-== Frequently Asked Questions ==
-
-= Question 1? =
-
-Answer 1.
-
-= Question 2? =
-
-Answer 2.
-
-== Screenshots ==
-
-1. Screenshot 1 description
-2. Screenshot 2 description
-
-== Changelog ==
-
-= 1.0.0 =
-* Initial release
-
-== Upgrade Notice ==
-
-= 1.0.0 =
-Initial release.
-```
-
-### Best Practices
-
-- **Contributors**: Use WordPress.org usernames
-- **Tags**: Maximum 12 tags, use existing popular tags
-- **Tested up to**: Keep updated with latest WordPress version
-- **Short description**: Clear, concise, under 150 characters
-- **Changelog**: Use semantic versioning, list all changes
-- **Screenshots**: Number them, provide clear descriptions
-
----
-
-## README.md (GitHub/Repository)
-
-### Structure
-
-```markdown
-# Plugin Name
-
-Brief description of the plugin.
-
-## Description
-
-Detailed description with features and benefits.
-
-## Features
-
-- Feature 1
-- Feature 2
-- Feature 3
-
-## Requirements
-
-- WordPress 6.0 or higher
-- PHP 7.4 or higher
-
-## Installation
-
-### From WordPress.org
-
-1. Go to Plugins > Add New
-2. Search for "Plugin Name"
-3. Click Install Now
-4. Activate the plugin
-
-### Manual Installation
-
-1. Download the plugin zip file
-2. Upload to `/wp-content/plugins/`
-3. Activate through WordPress admin
-
-### From Source
-
-```bash
-git clone https://github.com/username/plugin-name.git
-cd plugin-name
-composer install
-npm install
-npm run build
-```
-
-## Usage
-
-### Basic Usage
-
-```php
-// Example code
-```
-
-### Advanced Usage
-
-```php
-// Advanced example
-```
-
-## Configuration
-
-Configure the plugin at **Settings > Plugin Name**.
-
-Available options:
-- Option 1: Description
-- Option 2: Description
-
-## Hooks & Filters
-
-### Actions
-
-```php
-// Hook into plugin initialization
-add_action('my_plugin_init', 'my_custom_function');
-```
-
-### Filters
-
-```php
-// Filter plugin settings
-add_filter('my_plugin_settings', 'my_custom_filter');
-```
-
-## Development
-
-### Setup
-
-```bash
-composer install
-npm install
-```
-
-### Build
-
-```bash
-npm run build
-```
-
-### Testing
-
-```bash
-composer test
-npm test
-```
-
-## Contributing
-
-Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## License
-
-GPL-2.0+ - See [LICENSE](LICENSE) for details.
-
-## Support
-
-- [Documentation](https://example.com/docs)
-- [Support Forum](https://wordpress.org/support/plugin/plugin-name)
-- [Issue Tracker](https://github.com/username/plugin-name/issues)
-```
-
----
-
-## Inline Code Comments
-
-### When to Comment
-
-**DO comment:**
-- Complex algorithms or business logic
-- Non-obvious code behavior
-- Workarounds for WordPress/PHP quirks
-- Security-sensitive code
-- Performance optimizations
-
-**DON'T comment:**
-- Obvious code (e.g., `// Set variable`)
-- Self-explanatory function names
-- Code that can be refactored to be clearer
-
-### Comment Style
-
-```php
-// Single-line comment for brief explanations
-
-/*
- * Multi-line comment for longer explanations
- * that span multiple lines.
- */
-
-/**
- * DocBlock comment for functions, classes, and methods.
- * Always use DocBlocks for public APIs.
- */
-```
-
----
-
-## User Documentation
-
-### Admin Help Tabs
-
-```php
-add_action('admin_head', 'my_plugin_add_help_tabs');
-
-function my_plugin_add_help_tabs() {
-    $screen = get_current_screen();
-
-    $screen->add_help_tab(array(
-        'id'      => 'my_plugin_overview',
-        'title'   => __('Overview', 'my-plugin'),
-        'content' => '<p>' . __('Help content here.', 'my-plugin') . '</p>',
-    ));
-
-    $screen->set_help_sidebar(
-        '<p><strong>' . __('For more information:', 'my-plugin') . '</strong></p>' .
-        '<p><a href="https://example.com/docs">' . __('Documentation', 'my-plugin') . '</a></p>'
-    );
-}
-```
-
-### Contextual Help
-
-Provide help text near complex settings:
-
-```php
-<p class="description">
-    <?php _e('This setting controls...', 'my-plugin'); ?>
-</p>
-```
-
----
-
-## Changelog Management
-
-### Format
-
-Use [Keep a Changelog](https://keepachangelog.com/) format:
-
-```markdown
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [Unreleased]
-
-### Added
-- New feature description
-
-### Changed
-- Changed feature description
-
-### Deprecated
-- Deprecated feature description
-
-### Removed
-- Removed feature description
-
-### Fixed
-- Bug fix description
-
-### Security
-- Security fix description
-
-## [1.0.0] - 2024-01-15
-
-### Added
-- Initial release
-```
-
-### Version Numbering
-
-Follow [Semantic Versioning](https://semver.org/):
-
-- **MAJOR** (1.0.0 → 2.0.0): Breaking changes
-- **MINOR** (1.0.0 → 1.1.0): New features, backward compatible
-- **PATCH** (1.0.0 → 1.0.1): Bug fixes, backward compatible
-
----
-
-## Best Practices
-
-### Documentation Checklist
-
-- [ ] All public functions have PHPDoc comments
-- [ ] All classes have PHPDoc comments
-- [ ] All hooks (actions/filters) are documented
-- [ ] readme.txt is complete and up-to-date
-- [ ] README.md includes installation and usage instructions
-- [ ] Changelog is updated for each release
-- [ ] Code comments explain "why", not "what"
-- [ ] Admin help tabs provide contextual assistance
-- [ ] All user-facing strings are translatable
-
-### Maintenance
-
-- Update `Tested up to` with each WordPress release
-- Keep changelog current with each version
-- Review and update documentation quarterly
-- Remove outdated screenshots and examples
-- Update code examples to use current best practices
-
+# WordPress Plugin Documentation Standards
+
+## Overview
+
+This document defines documentation standards for WordPress plugins, covering inline code documentation (PHPDoc), readme.txt for WordPress.org, README.md for GitHub, and user-facing documentation.
+
+---
+
+## PHPDoc Standards
+
+### File Headers
+
+Every PHP file must include a file-level DocBlock:
+
+```php
+<?php
+/**
+ * Plugin Name: My Plugin
+ * Description: Brief description
+ * Version: 1.0.0
+ * Author: Author Name
+ * License: GPL-2.0+
+ * Text Domain: my-plugin
+ *
+ * @package    My_Plugin
+ * @subpackage My_Plugin/includes
+ * @author     Author Name <email@example.com>
+ * @license    GPL-2.0+ http://www.gnu.org/licenses/gpl-2.0.txt
+ * @link       https://example.com
+ * @since      1.0.0
+ */
+```
+
+### Class Documentation
+
+```php
+/**
+ * Main plugin class.
+ *
+ * Handles plugin initialization, loading dependencies, and defining hooks.
+ *
+ * @since      1.0.0
+ * @package    My_Plugin
+ * @subpackage My_Plugin/includes
+ * @author     Author Name <email@example.com>
+ */
+class My_Plugin {
+    
+    /**
+     * The unique identifier of this plugin.
+     *
+     * @since    1.0.0
+     * @access   protected
+     * @var      string    $plugin_name    The string used to uniquely identify this plugin.
+     */
+    protected $plugin_name;
+    
+    /**
+     * Initialize the plugin.
+     *
+     * Sets the plugin name and version, loads dependencies, defines locale,
+     * and sets up admin and public hooks.
+     *
+     * @since    1.0.0
+     */
+    public function __construct() {
+        // Constructor code
+    }
+}
+```
+
+### Function Documentation
+
+```php
+/**
+ * Retrieve posts with custom meta query.
+ *
+ * @since    1.0.0
+ * @param    array    $args    Query arguments.
+ * @param    bool     $cache   Whether to use cached results. Default true.
+ * @return   array|WP_Error    Array of posts or WP_Error on failure.
+ */
+function my_plugin_get_posts( $args = array(), $cache = true ) {
+    // Function code
+}
+```
+
+### Hook Documentation
+
+```php
+/**
+ * Fires after plugin initialization.
+ *
+ * @since 1.0.0
+ * @param My_Plugin $plugin The main plugin instance.
+ */
+do_action( 'my_plugin_initialized', $this );
+
+/**
+ * Filters the plugin settings before saving.
+ *
+ * @since 1.0.0
+ * @param array $settings The plugin settings array.
+ * @param int   $user_id  The current user ID.
+ */
+$settings = apply_filters( 'my_plugin_settings', $settings, get_current_user_id() );
+```
+
+### Required PHPDoc Tags
+
+- `@since` - Version when introduced (required for all)
+- `@param` - Parameter description (required for functions/methods with parameters)
+- `@return` - Return value description (required for functions/methods that return values)
+- `@access` - Access level (public, protected, private) for properties
+- `@var` - Variable type for properties
+- `@package` - Package name
+- `@author` - Author information
+- `@link` - Related URL
+- `@see` - Related function/class
+- `@deprecated` - Deprecation notice with version and alternative
+
+---
+
+## readme.txt (WordPress.org)
+
+### Structure
+
+```
+=== Plugin Name ===
+Contributors: username1, username2
+Donate link: https://example.com/donate
+Tags: tag1, tag2, tag3
+Requires at least: 6.0
+Tested up to: 6.4
+Requires PHP: 7.4
+Stable tag: 1.0.0
+License: GPLv2 or later
+License URI: http://www.gnu.org/licenses/gpl-2.0.html
+
+Short description (max 150 characters).
+
+== Description ==
+
+Detailed description of the plugin.
+
+**Key Features:**
+
+* Feature 1
+* Feature 2
+* Feature 3
+
+**Use Cases:**
+
+* Use case 1
+* Use case 2
+
+== Installation ==
+
+1. Upload the plugin files to `/wp-content/plugins/my-plugin`
+2. Activate the plugin through the 'Plugins' menu
+3. Configure settings at Settings > My Plugin
+
+== Frequently Asked Questions ==
+
+= Question 1? =
+
+Answer 1.
+
+= Question 2? =
+
+Answer 2.
+
+== Screenshots ==
+
+1. Screenshot 1 description
+2. Screenshot 2 description
+
+== Changelog ==
+
+= 1.0.0 =
+* Initial release
+
+== Upgrade Notice ==
+
+= 1.0.0 =
+Initial release.
+```
+
+### Best Practices
+
+- **Contributors**: Use WordPress.org usernames
+- **Tags**: Maximum 12 tags, use existing popular tags
+- **Tested up to**: Keep updated with latest WordPress version
+- **Short description**: Clear, concise, under 150 characters
+- **Changelog**: Use semantic versioning, list all changes
+- **Screenshots**: Number them, provide clear descriptions
+
+---
+
+## README.md (GitHub/Repository)
+
+### Structure
+
+```markdown
+# Plugin Name
+
+Brief description of the plugin.
+
+## Description
+
+Detailed description with features and benefits.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Requirements
+
+- WordPress 6.0 or higher
+- PHP 7.4 or higher
+
+## Installation
+
+### From WordPress.org
+
+1. Go to Plugins > Add New
+2. Search for "Plugin Name"
+3. Click Install Now
+4. Activate the plugin
+
+### Manual Installation
+
+1. Download the plugin zip file
+2. Upload to `/wp-content/plugins/`
+3. Activate through WordPress admin
+
+### From Source
+
+```bash
+git clone https://github.com/username/plugin-name.git
+cd plugin-name
+composer install
+npm install
+npm run build
+```
+
+## Usage
+
+### Basic Usage
+
+```php
+// Example code
+```
+
+### Advanced Usage
+
+```php
+// Advanced example
+```
+
+## Configuration
+
+Configure the plugin at **Settings > Plugin Name**.
+
+Available options:
+- Option 1: Description
+- Option 2: Description
+
+## Hooks & Filters
+
+### Actions
+
+```php
+// Hook into plugin initialization
+add_action('my_plugin_init', 'my_custom_function');
+```
+
+### Filters
+
+```php
+// Filter plugin settings
+add_filter('my_plugin_settings', 'my_custom_filter');
+```
+
+## Development
+
+### Setup
+
+```bash
+composer install
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+composer test
+npm test
+```
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+GPL-2.0+ - See [LICENSE](LICENSE) for details.
+
+## Support
+
+- [Documentation](https://example.com/docs)
+- [Support Forum](https://wordpress.org/support/plugin/plugin-name)
+- [Issue Tracker](https://github.com/username/plugin-name/issues)
+```
+
+---
+
+## Inline Code Comments
+
+### When to Comment
+
+**DO comment:**
+- Complex algorithms or business logic
+- Non-obvious code behavior
+- Workarounds for WordPress/PHP quirks
+- Security-sensitive code
+- Performance optimizations
+
+**DON'T comment:**
+- Obvious code (e.g., `// Set variable`)
+- Self-explanatory function names
+- Code that can be refactored to be clearer
+
+### Comment Style
+
+```php
+// Single-line comment for brief explanations
+
+/*
+ * Multi-line comment for longer explanations
+ * that span multiple lines.
+ */
+
+/**
+ * DocBlock comment for functions, classes, and methods.
+ * Always use DocBlocks for public APIs.
+ */
+```
+
+---
+
+## User Documentation
+
+### Admin Help Tabs
+
+```php
+add_action('admin_head', 'my_plugin_add_help_tabs');
+
+function my_plugin_add_help_tabs() {
+    $screen = get_current_screen();
+
+    $screen->add_help_tab(array(
+        'id'      => 'my_plugin_overview',
+        'title'   => __('Overview', 'my-plugin'),
+        'content' => '<p>' . __('Help content here.', 'my-plugin') . '</p>',
+    ));
+
+    $screen->set_help_sidebar(
+        '<p><strong>' . __('For more information:', 'my-plugin') . '</strong></p>' .
+        '<p><a href="https://example.com/docs">' . __('Documentation', 'my-plugin') . '</a></p>'
+    );
+}
+```
+
+### Contextual Help
+
+Provide help text near complex settings:
+
+```php
+<p class="description">
+    <?php _e('This setting controls...', 'my-plugin'); ?>
+</p>
+```
+
+---
+
+## Changelog Management
+
+### Format
+
+Use [Keep a Changelog](https://keepachangelog.com/) format:
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- New feature description
+
+### Changed
+- Changed feature description
+
+### Deprecated
+- Deprecated feature description
+
+### Removed
+- Removed feature description
+
+### Fixed
+- Bug fix description
+
+### Security
+- Security fix description
+
+## [1.0.0] - 2024-01-15
+
+### Added
+- Initial release
+```
+
+### Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (1.0.0 → 2.0.0): Breaking changes
+- **MINOR** (1.0.0 → 1.1.0): New features, backward compatible
+- **PATCH** (1.0.0 → 1.0.1): Bug fixes, backward compatible
+
+---
+
+## Best Practices
+
+### Documentation Checklist
+
+- [ ] All public functions have PHPDoc comments
+- [ ] All classes have PHPDoc comments
+- [ ] All hooks (actions/filters) are documented
+- [ ] readme.txt is complete and up-to-date
+- [ ] README.md includes installation and usage instructions
+- [ ] Changelog is updated for each release
+- [ ] Code comments explain "why", not "what"
+- [ ] Admin help tabs provide contextual assistance
+- [ ] All user-facing strings are translatable
+
+### Maintenance
+
+- Update `Tested up to` with each WordPress release
+- Keep changelog current with each version
+- Review and update documentation quarterly
+- Remove outdated screenshots and examples
+- Update code examples to use current best practices
+