doc_widget 0.1.3

An easier way that documents your widgets.

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

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

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:

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:doc_widget/doc_widget.dart';

@docWidget
class Button extends StatelessWidget {
  // ...  
}

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
Type	Type of the parameter
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 title = Title(title: "Amazing");
/// ```
@docWidget
class Title extends StatelessWidget {
  // ...
}

Generated file

The generated code should be similar to this but don't worry about this, all this information will be used and rendered for doc_widget. All generated file contains a suffix DocWidget to help you to differentiate of widget.

• Widget file: title.dart

import 'package:doc_widget/doc_widget.dart';

/// ```dart
/// final title = Title(title: "Amazing");
/// ```
@docWidget
class Title extends StatelessWidget {
  Title({ this.title = 'Amazing' });

  final String title;
}

• Generated file by doc_widget: title.doc_widget.dart

// title.doc_widget.dart

class TitleDocWidget implements Documentation {
  @override
  String get name => 'Title';
  @override
  List<PropertyDoc> get properties => [
        PropertyDoc(
          name: 'title',
          isRequired: false,
          type: 'String',
          defaultValue: 'Amazing',
        ),
      ];
  @override
  String get snippet => '''final title = Title(title: 'Amazing');''';
}

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 titleItem = ElementPreview(
    document: TitleDoc(), // From generated file
    previews: [
      WidgetPreview( // This will show your widget and a description about.
          widget: Title(title: 'Amazing'),
          description: 'With text Amazing',
      ),
    ],
  );

  runApp(DocPreview(elements: [titleItem])); // 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",
        },
    ]
}