doc_widget 0.2.4

An easier way that documents your widgets.

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
  • VSCode launch
  • Exclude files from Analyzer

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.

Name	Description
Name	Name of the parameter if is named
Type	Type of the parameter (null-safety)
Required	Whether your parameter is required or not
Default value	If 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

You have many ways that create an application that will read and rendering the documentation. I will list two ways:

• Running your own project with a different target.
• Creating another application inside our project/package. Example: documentation

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 use the first approach here and create a file lib/doc_widget.dart like the 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.

If you prefer, you can run the doc_widget and host it with flutter web.

flutter run -d chrome -t lib/doc_widget.dart

VSCode launch

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

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "doc_widget - Mobile",
      "request": "launch",
      "type": "dart",
      "program": "lib/doc_widget.dart"
    },
    {
      "name": "doc_widget - Web",
      "request": "launch",
      "type": "dart",
      "program": "lib/doc_widget.dart",
      "args": ["-d", "chrome"]
    },
    {
      "name": "main app",
      "request": "launch",
      "type": "dart",
      "program": "lib/main.dart"
    }
  ]
}

Exclude files from Analyzer

In the case of the need to removed generated files from the analyzer, see below how to exclude them.

analyzer:
  exclude:
    - "**/*.doc_widget.dart"