Doc Widget #

Do you need to create documentation that contains all information about your widgets? Don't worry, doc_widget will make this easier for you.

Indice #

• What this solve?
• Quick start
• How to use
  • Install
  • How to generate
  • Features
    • Parameters
    • Snippet
  • Generated file
  • Doc preview
    • How to run

What this solve? #

As we don’t have a reflection in Flutter, we cannot access informations about properties of a Widget, like a type and name of a properties for example. Besides that, we don't need to create another application that will show your widgets, doc_widget makes this easier.

Quick Start #

• Install the dependencies.
  • dependencies: doc_widget
  • dev_dependencies: doc_widget_builder, build_runner
• Annotate widgets with @docWidget.

@docWidget
class Button extends StatelessWidget

• Run build_runner to generate code. This will generate the documentation code.

flutter pub run build_runner build

• Create a lib/doc_widget.dart file to use the documentation code. Use DocPreview application in lib/doc_widget.dart and run this as a target file. flutter run -t lib/doc_widget.dart

For more details, see Example and see How to use for a complete guide.

How to use #

Install #

To use doc_widget you need to install doc_widget, doc_widget_builder and typical build_runner/code-generator setup.

# pubspec.yaml
dependencies:
  doc_widget: latest_version

dev_dependencies:
  doc_widget_builder: latest_version
  build_runner: latest_version

latest_version:

• doc_widget is a package that contains annotations and the application preview for your widgets.
• doc_widget_builder, the code generator to generate the documentation.
• build_runner, the tool to run code-generators.

How to generate #

You will need to annotate your Widget with docWidget annotation and after generate the code with all information about your widget.

import 'package:flutter/cupertino.dart';
import 'package:doc_widget/doc_widget.dart';

@docWidget
class Button extends StatelessWidget {
  Button(
    this.text, {
    @required this.onPressed,
    this.color = const Color(0xff007aff),
  });

  final String text;
  final void Function() onPressed;
  final Color color;

  @override
  Widget build(BuildContext context) {
    return CupertinoButton(
      color: color,
      onPressed: onPressed,
      child: Text(text),
    );
  }
}

After this, you need run the runner_build using this command bellow:

flutter pub run build_runner build

Features #

Parameters #

The code generator will contain all information about your parameters.

Snippet #

You can describe how to use your widget with Snippet. You need to use a Documentation Comment /// and wrap your snippet inside dart special formatter.

Below has an example of how to document your widget.

import 'package:doc_widget/doc_widget.dart';

/// ```dart
/// final button = Button(
///  'Button',
///  onPressed: () => print('Doc Widget'),
/// );
/// ```
@docWidget
class Button extends StatelessWidget {
  // ...
}

Generated file #

Don't worry about generated code, all this information will be used and rendered by doc_widget. All generated files contains a prefix *.doc_widget.dart. The generated class contains a suffix DocWidget to help you to differentiate of the widget.

The only information that you need to know is the class name, in this case, is ButtonDocWidget.

// button.doc_widget.dart

class ButtonDocWidget implements Documentation {
  // ...
}

Doc Preview #

This is a flutter application that the main responsibility is to read all information generated and show your documentation. This job is manual and you need to insert all generated files in *.doc_widget.dart.

We recommend create a file lib/doc_widget.dart like a example below.

// lib/doc_widget.dart

void main() {

  final button = ElementPreview(
    document: ButtonDocWidget(), // From generated file
    previews: [
      WidgetPreview( // This will show your widget and a description about.
        widget: Button(
          'Button',
          onPressed: () => print('Hello'),
        ),
        description: 'Default button.',
      ),
    ],
  );

  runApp(DocPreview(elements: [button])); // Application that will show all elements.
}

How to run #

After creating a file that contains your doc files lib/doc_widget.dart, you need to run the application with lib/doc_widget.dart as a target.

flutter run -t lib/doc_widget.dart

You use VSCode? You can insert .vscode/launch.json to automate this job.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "doc_widget app",
      "request": "launch",
      "type": "dart",
      "program": "lib/doc_widget.dart"
    },
    {
      "name": "main app",
      "request": "launch",
      "type": "dart",
      "program": "lib/main.dart"
    }
  ]
}