Doc Widget

Uma alternativa para documentar seus widgets

Motivação

Como poderíamos ter a possibilidade de automaticamente ter uma forma ou ferramenta que nos desse a possibilidade de criar uma documentação demonstrando as informações dos nossos Widgets?

Utilizei como base bibliotecas como Storybook e Docz para termos o doc_widget como uma alternativa no lado do Flutter.

Documentação

Se você possui um grande time, provavelmente já se deparou com a necessidade de sempre ter que mencionar Widgets existentes para atenderem uma determinada demanda. Seria mais eficaz caso tivéssemos uma aplicação que listasse todos os Widgets presentes na nossa aplicação, contendo suas propriedades e exemplos de como utilizá-los. Isso irá facilitar o uso, a busca e otimização na curva de aprendizado de novos desenvolvedores que venham ingressar em seu time.

Doc Widget

Recentemente criei uma versão inicial do doc_widget que provê de forma simples, a possibilidade de termos informações de nossos Widgets.

Instalação

Precisamos instalar o doc_widget como uma dependência,doc_widget_builder e build_runner como dependência de desenvolvimento.

# pubspec.yaml
dependencies:
  doc_widget: 

dev_dependencies:
  doc_widget_builder:
  build_runner:

obs: Verificar a versão atual pelo link https://pub.dev/packages/doc_widget

Conhecendo seus widgets

Aqui iremos exemplificar como podemos criar uma documentação de um determinado Widget já existente. Neste caso, iremos documentar o widget Button

Agora iremos utilizar doc_widget nesse nosso Widget para que possamos gerar um arquivo button.doc_widget.dart que contenha as informações necessárias que para serem consumidos pela aplicação também contida em nossa biblioteca. Calma, esse arquivo será gerado automaticamente, iremos ver isso mais a frente.

Bora lá, primeiro precisamos anotar nosso Widget com a anotação@docWidget como demonstrado abaixo.

@docWidget
class Button extends Stateless

Caso você queira aprimorar sua documentação, também é possível disponibilizar um demonstrativo de como utilizar o seu Widget. Você precisará utilizar a sintaxe de documentação, envolvendo o seu código em bloco de código semelhante ao que usamos em markdown como demonstrado abaixo.

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

Feito isso, já teremos o suficiente para poder gerar a documentação e o seu Widget ficará assim após o fim da anotação.

Gerando código

Lembra que mencionei que os arquivos seriam gerados automaticamente? Finalizado a etapa de anotar nosso Widget, agora precisamos gerar nossos arquivos *.doc_widget.dart utilizando build_runner.

flutter pub run build_runner build

Criando a aplicação doc_widget

Agora que temos nossos arquivos gerados, precisamos criar uma aplicação secundária que irá ler e compreender esses arquivos. Esse trabalho é manual.

Criarei um arquivo em lib/doc_widget.dart que será uma nova aplicação. Não se preocupe, isso não irá afetar a sua aplicação. Feita a criação, iremos seguir o solicitado em nossa documentação e teremos algo semelhante ao abaixo.

Visualizar nossa documentação

Depois de criar os arquivos contendendo seus docs, precisamos executar a nossa aplicação que está localizada em lib/doc_widget.dart

Basta executar o comando passando o target para o arquivo mencionado.

flutter run -t lib/doc_widget.dart

Feedbacks e contribuição

A ferramenta como já dito anteriormente possui uma versão inicial e ainda está em fase de testes. A ferramenta te ajudou? Acha que não faz sentido usar? É desnecessária?
É super importante que a comunidade nos ajude a testar, conhecer e contribuir. Viu algo em que possamos aprimorar? Algo que que possamos mudar? Não deixe de contribuir, vamos evoluir a ferramenta de forma conjunta.

Flutter Package e Github

doc_widget | Flutter Package

isacjunior/doc_widget