Forms: add docs (#46047)

* add comprehensive docs

* changelog

Author: CGastrell

projects/packages/forms/changelog/add-forms-docs

@@ -0,0 +1,4 @@
+Significance: patch
+Type: added
+
+Forms: add docs on classes and usage

projects/packages/forms/docs/README.md

@@ -0,0 +1,117 @@
+# Jetpack Forms Documentation
+
+Welcome to the Jetpack Forms package documentation. This package provides WordPress form functionality including contact forms, feedback storage, and form processing.
+
+## Core Classes
+
+### Feedback System
+
+The feedback system handles form submission data storage and retrieval:
+
+- **[Feedback](feedback.md)** ([Class Reference](feedback-class.md)) - Main class representing a form submission stored as a custom WordPress post (`feedback` post type). Provides methods for creating, retrieving, and managing form responses including author info, field data, and submission metadata.
+
+- **[Feedback_Field](feedback-field.md)** ([Class Reference](feedback-field-class.md)) - Represents an individual form field submission with its label, value, and type. Handles context-specific rendering for emails, CSV exports, API responses, and web display.
+
+- **[Feedback_Author](feedback-author.md)** ([Class Reference](feedback-author-class.md)) - Manages submitter information including name, email, URL, and avatar. Integrates with WordPress comment filters for consistent data handling.
+
+- **[Feedback_Source](feedback-source.md)** ([Class Reference](feedback-source-class.md)) - Tracks the source context of a form submission (post, page, widget, or block template). Provides permalinks and edit URLs based on submission origin.
+
+### Form System
+
+Classes that handle form rendering and processing:
+
+- **Contact_Form** - Core form class that parses shortcodes, validates fields, and processes submissions. Handles form attributes, field definitions, and submission workflow.
+
+- **Contact_Form_Field** - Represents a form field definition (not the submitted data). Defines field properties like type, label, validation rules, and rendering options.
+
+- **Contact_Form_Shortcode** - Handles WordPress shortcode parsing for `[contact-form]` and `[contact-field]` shortcodes. Converts shortcode attributes into form objects.
+
+- **Contact_Form_Plugin** - Main plugin class that initializes the forms system, registers hooks, and coordinates between components.
+
+- **Contact_Form_Endpoint** - REST API endpoint handler for form submissions. Processes AJAX submissions and returns JSON responses.
+
+### UI Components
+
+Classes for admin and user-facing interfaces:
+
+- **Admin** - Admin interface for viewing and managing form submissions. Provides list tables and detail views for feedback posts.
+
+- **Editor_View** - Handles form display in the block editor. Provides live previews and editing capabilities.
+
+- **Form_View** - Renders forms on the frontend. Handles HTML generation, validation display, and success messages.
+
+### Utilities
+
+Helper classes:
+
+- **Util** - Utility functions for common operations like sanitization, validation, and data formatting.
+
+- **Form_Submission_Error** - Exception class for handling form submission errors. Provides structured error information for validation failures and processing issues.
+
+## Quick Start
+
+### Creating a Form Submission
+
+```php
+use Automattic\Jetpack\Forms\ContactForm\Feedback;
+use Automattic\Jetpack\Forms\ContactForm\Contact_Form;
+
+$form = new Contact_Form( $attributes, $content );
+$feedback = Feedback::from_submission( $_POST, $form, get_post() );
+$post_id = $feedback->save();
+```
+
+### Retrieving a Submission
+
+```php
+$feedback = Feedback::get( $post_id );
+echo $feedback->get_author();
+echo $feedback->get_author_email();
+
+foreach ( $feedback->get_fields() as $field ) {
+    echo $field->get_label() . ': ' . $field->get_render_value();
+}
+```
+
+## Testing
+
+Tests are located in `tests/php/contact-form/`:
+- `Feedback_Test.php` - Comprehensive feedback system tests
+- `Feedback_Field_Test.php` - Field handling tests
+- `Contact_Form_Test.php` - Form processing tests
+
+Run tests:
+```bash
+jetpack docker phpunit projects/packages/forms
+```
+
+## File Structure
+
+```
+src/contact-form/
+├── class-feedback.php           # Main feedback class
+├── class-feedback-field.php     # Field data class
+├── class-feedback-author.php    # Author info class
+├── class-feedback-source.php    # Source context class
+├── class-contact-form.php       # Form definition class
+├── class-contact-form-field.php # Field definition class
+└── ...
+
+tests/php/contact-form/
+├── Feedback_Test.php
+├── Feedback_Field_Test.php
+└── ...
+
+docs/
+├── README.md                    # This file
+├── feedback.md                  # Feedback class docs
+├── feedback-field.md            # Field class docs
+├── feedback-author.md           # Author class docs
+└── feedback-source.md           # Source class docs
+```
+
+## Additional Resources
+
+- [Jetpack Forms Block Editor Integration](../README.md)
+- [Form Submission Workflow](#) (TBD)
+- [Security and Validation](#) (TBD)

projects/packages/forms/docs/feedback-author-class.md

@@ -0,0 +1,262 @@
+# Feedback_Author Class Reference
+
+**[→ User Guide](feedback-author.md)** | **[← Back to Index](README.md)**
+
+Technical reference for `Automattic\Jetpack\Forms\ContactForm\Feedback_Author`
+
+**Source:** [`class-feedback-author.php`](../src/contact-form/class-feedback-author.php)
+
+## Constructor
+
+### `__construct()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L61)
+
+```php
+public function __construct(
+    string $name = '',
+    string $email = '',
+    string $url = '',
+    string $first_name = '',
+    string $last_name = ''
+)
+```
+
+**Parameters:**
+- `$name` (string) - The name of the author
+- `$email` (string) - The email of the author
+- `$url` (string) - The URL of the author
+- `$first_name` (string) - The first name of the author
+- `$last_name` (string) - The last name of the author
+
+All parameters are optional and default to empty strings.
+
+---
+
+## Static Methods
+
+### `from_submission()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L76)
+
+Create a Feedback_Author instance from the submission data.
+
+```php
+public static function from_submission(
+    array $post_data,
+    Contact_Form $form
+): Feedback_Author
+```
+
+**Parameters:**
+- `$post_data` (array) - The post data from the form submission
+- `$form` (Contact_Form) - The form object
+
+**Returns:** `Feedback_Author` - New author instance with filtered data
+
+**Note:** Automatically applies WordPress comment filters (`pre_comment_author_name`, `pre_comment_author_email`, `pre_comment_author_url`).
+
+---
+
+## Instance Methods
+
+### `get_display_name()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L129)
+
+Get the display name of the author.
+
+```php
+public function get_display_name(): string
+```
+
+**Returns:** `string` - The author's name, or email if name is empty
+
+**Behavior:** Falls back to email if name is not set, ensuring a non-empty display value.
+
+---
+
+### `get_name()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L150)
+
+Get the name of the author.
+
+```php
+public function get_name(): string
+```
+
+**Returns:** `string` - The author's name
+
+**Behavior:**
+- If both `first_name` and `last_name` are set, combines them with space and applies `pre_comment_author_name` filter
+- Otherwise returns the stored `name` value (already filtered during construction)
+
+---
+
+### `get_email()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L169)
+
+Get the email of the author.
+
+```php
+public function get_email(): string
+```
+
+**Returns:** `string` - The author's email address
+
+---
+
+### `get_url()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L178)
+
+Get the URL of the author.
+
+```php
+public function get_url(): string
+```
+
+**Returns:** `string` - The author's website URL
+
+---
+
+### `get_first_name()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L187)
+
+Get the first name of the author (if provided separately).
+
+```php
+public function get_first_name(): string
+```
+
+**Returns:** `string` - The author's first name
+
+---
+
+### `get_last_name()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L196)
+
+Get the last name of the author (if provided separately).
+
+```php
+public function get_last_name(): string
+```
+
+**Returns:** `string` - The author's last name
+
+---
+
+### `get_avatar_url()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L141)
+
+Get the avatar URL of the author.
+
+```php
+public function get_avatar_url(): string
+```
+
+**Returns:** `string` - The Gravatar URL, or empty string if email is not set
+
+**Note:** Uses WordPress `get_avatar_url()` function.
+
+---
+
+## Private Static Methods
+
+### `get_computed_author_info()`
+[📍 Source](../src/contact-form/class-feedback-author.php#L98)
+
+Gets the computed author information with filter application.
+
+```php
+private static function get_computed_author_info(
+    array $post_data,
+    string $type,
+    string $filter,
+    Contact_Form $form
+): string
+```
+
+**Parameters:**
+- `$post_data` (array) - The post data from the form submission
+- `$type` (string) - The type of author information to retrieve ('name', 'email', 'url')
+- `$filter` (string) - Filter to apply to the value
+- `$form` (Contact_Form) - The form object
+
+**Returns:** `string` - Filtered value for the author information
+
+**Applied Filters:**
+- `pre_comment_author_name`
+- `pre_comment_author_email`
+- `pre_comment_author_url`
+
+---
+
+## WordPress Filter Integration
+
+The class integrates with WordPress comment filters during construction and when combining first/last names:
+
+### Applied Filters
+
+| Filter | Applied To | Purpose |
+|--------|-----------|---------|
+| `pre_comment_author_name` | Name field | Sanitize and validate author name |
+| `pre_comment_author_email` | Email field | Sanitize and validate email |
+| `pre_comment_author_url` | URL field | Sanitize and validate URL |
+
+### Filter Pattern
+
+Filters are applied using this pattern:
+```php
+Contact_Form_Plugin::strip_tags(
+    stripslashes(
+        apply_filters( $filter, addslashes( $value ) )
+    )
+);
+```
+
+This ensures compatibility with WordPress comment handling while preventing XSS.
+
+---
+
+## Usage Examples
+
+### Basic Usage
+```php
+$author = new Feedback_Author(
+    'John Doe',
+    '[email protected]',
+    'https://johndoe.com'
+);
+
+echo $author->get_display_name(); // "John Doe"
+echo $author->get_email();        // "[email protected]"
+```
+
+### With First/Last Name
+```php
+$author = new Feedback_Author(
+    '',  // name
+    '[email protected]',
+    'https://johndoe.com',
+    'John',  // first_name
+    'Doe'    // last_name
+);
+
+echo $author->get_name(); // "John Doe" (combined and filtered)
+```
+
+### Display Name Fallback
+```php
+// No name provided
+$author = new Feedback_Author( '', '[email protected]' );
+echo $author->get_display_name(); // "[email protected]"
+
+// With name
+$author = new Feedback_Author( 'John Doe', '[email protected]' );
+echo $author->get_display_name(); // "John Doe"
+```
+
+---
+
+## See Also
+
+- [Feedback_Author User Guide](feedback-author.md) - Usage examples and patterns
+- [Feedback Class Reference](feedback-class.md)
+- [Contact_Form Class](#) - Provides field IDs for author extraction