Parent: #186
Related: #134, #135, #136
Problem
State management generated code is a public authoring surface. If generated Dartdoc is noisy, fake, or inconsistent with VGV Flutter lint style, users and AI agents will copy bad patterns. Current generated docs still include stale examples like closure select(...) and fake field names in some templates.
Goal
Make runtime package docs and generated state code docs VGV-style, concise, real, and aligned with the approved state API.
Scope
- Public generated APIs get Dartdoc: base class, scope, watch proxy, selector widget, builder alias if kept, listener, and BuildContext extension.
- Private generated internals use normal
// comments only.
- Remove stale closure-backed
select(...) examples from generated docs.
- Remove fake examples unless the generated test state actually has that field.
- Use real examples from the state showcase/tests.
- Keep docs short and IDE-useful.
- Align state docs with
very_good_analysis expectations where practical.
Example Style
/// Provides [ShellViewModel] to the widget tree.
///
/// The scope can create and own a ViewModel, or expose an existing ViewModel
/// using [ShellViewModelScope.value].
class ShellViewModelScope extends StatefulWidget {}/// Builds from a selected [ShellState] value.
///
/// The selector listens to [ShellViewModel] and rebuilds only when the selected
/// value changes.
class ShellViewModelSelector<R> extends StatefulWidget {}Acceptance Criteria
- Generated docs do not mention rejected APIs as recommended paths.
- Public generated types have useful Dartdoc.
- Private generated types do not carry long Dartdoc blocks.
- Dart/package analysis passes with docs/lint expectations for affected packages/examples.
- Snapshot tests lock the generated doc shape.
Validation
cargo test -p dust_state_plugin docsdart analyze / flutter analyze for affected packages/examples.
Risks
Do not turn generated code into documentation essays. The goal is short IDE help and correct examples.
Parent: #186
Related: #134, #135, #136
Problem
State management generated code is a public authoring surface. If generated Dartdoc is noisy, fake, or inconsistent with VGV Flutter lint style, users and AI agents will copy bad patterns. Current generated docs still include stale examples like closure
select(...)and fake field names in some templates.Goal
Make runtime package docs and generated state code docs VGV-style, concise, real, and aligned with the approved state API.
Scope
//comments only.select(...)examples from generated docs.very_good_analysisexpectations where practical.Example Style
Acceptance Criteria
Validation
cargo test -p dust_state_plugin docsdart analyze/flutter analyzefor affected packages/examples.Risks
Do not turn generated code into documentation essays. The goal is short IDE help and correct examples.