doc_widget 0.2.2
doc_widget: ^0.2.2 copied to clipboard

Flutter Android iOS Linux macOS web Windows

An easier way that documents your widgets.

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 #

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

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: latest_version

dev_dependencies:
  doc_widget_builder: latest_version
  build_runner: latest_version

latest_version: Pub

  • 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 #

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.

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

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"
22
likes
90
pub points
61%
popularity

Publisher

isacjunior.dev

An easier way that documents your widgets.

Repository (GitHub)
View/report issues

Documentation

API reference

License

MIT (LICENSE)

Dependencies

doc_widget_annotation, flutter, flutter_highlight

More

Packages that depend on doc_widget