[Roadmap]: Documentation

[al6uiz]

Background

MewUI currently has README-level documentation, samples, and issue/discussion-based explanations. As the framework grows in public API surface, controls, platform support, and first-party extensions, documentation needs to become an official and maintainable part of the project.

This issue tracks the overall documentation roadmap for MewUI. Detailed work will be managed through sub-issues.

Goals

• Establish an official documentation structure for MewUI.
• Provide generated and versioned API reference documentation.
• Separate user guides, conceptual documentation, control documentation, architecture documentation, and API reference.
• Automate documentation build, validation, and publishing where practical.
• Keep documentation synchronized with source changes and releases.
• Eventually provide complete documentation for all public controls.
• Provide contributor-level architecture documentation for the framework internals.

Documentation structure

The documentation should be organized into the following major areas:

Documentation
├─ Getting Started
├─ Concepts
├─ Guides
├─ Controls
├─ Extensions
├─ Platform Notes
├─ Architecture
├─ Troubleshooting
├─ API Reference
└─ Contributing

Scope

User-facing documentation

User-facing documentation should help application developers understand and use MewUI without having to infer behavior from samples or source code.

Initial areas:

• Installation and project setup
• First application
• Application lifecycle
• Window and dialog usage
• Layout system
• Input, focus, and hit testing
• Styling and themes
• Images and vector sources
• NativeAOT publishing
• Deployment notes

Control documentation

Each public control should eventually have its own documentation page using a consistent template.

Suggested control page template:

# ControlName

## Overview
## Basic usage
## Content model
## Layout behavior
## Input behavior
## Important properties
## Events
## Styling
## Examples
## Limitations
## Related controls

The initial phase should document only high-priority controls. Full control documentation coverage will be handled as a later phase.

API Reference

MewUI should provide an official API reference generated from XML documentation comments.

The API reference should cover:

• Namespaces
• Classes
• Structs
• Interfaces
• Enums
• Properties
• Methods
• Events
• Extension methods

The API reference should not replace guides or conceptual documentation. It should serve as the precise reference for public API shape and behavior.

Architecture documentation

Architecture documentation should target contributors and advanced users.

Long-term topics include:

• Rendering backend model
• Graphics context abstraction
• Windowing abstraction
• Layout system internals
• Input system
• Hit test pipeline
• Popup and overlay model
• Property system
• Platform integration
• Extension model

Contributor-level architecture documentation is part of the final documentation scope, even if it is not completed in the first phase.

Automation

Documentation should be integrated into the build and release workflow.

Planned automation areas:

• Generate API reference from XML documentation comments.
• Build the documentation site in CI.
• Validate internal documentation links.
• Validate code snippets where practical.
• Detect undocumented public APIs where practical.
• Publish documentation through GitHub Pages or an equivalent static hosting target.
• Keep API reference versioned with releases.
• Optionally publish preview documentation from the main branch.

Versioning

Documentation should distinguish stable and preview content.

Proposed versioning model:

latest    - latest stable release
preview   - main branch or preview package state
archived  - selected previous versions when API or behavior changed significantly

Version-specific pages should indicate the applicable version where needed.

Example:

Applies to: MewUI 0.19.0+

Phasing

Phase 1: Infrastructure

• Decide documentation tooling.
• Add documentation site structure.
• Enable XML documentation output.
• Add API reference generation.
• Add documentation build workflow.
• Add documentation publishing workflow.
• Define documentation style and terminology rules.

Phase 2: Initial documentation

• Add Getting Started documentation.
• Add core Concepts documentation.
• Add initial Guides.
• Add control documentation template.
• Add initial high-priority control pages.
• Add extension documentation structure.
• Add architecture documentation structure.

Phase 3: Coverage expansion

• Complete documentation for every public control.
• Expand XML documentation coverage across the public API surface.
• Add platform notes.
• Add troubleshooting documentation.
• Add migration and compatibility notes where needed.
• Add stronger automation for API and documentation consistency.

Phase 4: Contributor documentation

• Add contributor-level architecture documentation.
• Document rendering, layout, windowing, input, hit testing, property system, and platform integration internals.
• Document extension architecture and first-party extension boundaries.

Tracking

Detailed work should be split into sub-issues under this roadmap issue.

Proposed sub-issues:

• Documentation tooling and publishing
• API reference generation
• XML documentation coverage
• Documentation structure and style guide
• Getting Started documentation
• Concepts documentation
• Guides documentation
• Control documentation template
• Initial control documentation
• Full control documentation coverage
• Extension documentation
• Platform notes
• Troubleshooting documentation
• Contributor architecture documentation
• Documentation release workflow

Non-goals for the first phase

The following items are deferred from the initial infrastructure phase, but remain part of the overall roadmap:

• Complete documentation for every control.
• Complete contributor-level architecture documentation.
• Full troubleshooting documentation.
• Full migration documentation.
• Full documentation localization.
• Full compatibility documentation for every platform combination.

Expected outcome

MewUI should have an official documentation system that supports both user-facing documentation and generated API reference documentation.

The documentation should make common usage clearer, reduce repeated explanations in issues and discussions, and provide a maintainable foundation for future releases.