doc_widget 0.1.5

Flutter Android iOS web

An easier way that documents your widgets.

Doc Widget #

Build Pub

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 #

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

Doc Widget

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:

dev_dependencies:
  doc_widget_builder:
  build_runner:
  • 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.

NameDescription
NameName of the parameter if is named
TypeType of the parameter
RequiredWhether your parameter is required or not
Default valueIf has default value, this will show

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",
        },
    ]
}