Flutter — how to document your code

Dart Documentation

Introduction

Today you will learn how to make a documentation in a professional, complete way, following the documentation rules passed by Dart and generating a website of your documentation.

Why document it?

Think of the code you wrote this week as you evaluate his assertiveness? And in three months will the assertiveness still be the same?

Many developers write code as if it were cycling “ once written you never forget” but things are not quite like that, we write thousands of lines every month and sometimes work on different projects which causes a large flow of information from the same subject, so when we look at a code 3 months ago and see a variable with the name “isAccepted “ really will not understand the context just by name, after all in which he, she or that is being accepted ?

And that’s when you think, oh if you had a documentation of my code equal to the language I use, and you could have it, but you think it’s very complicated to do all those sites and references of classes, variables and functions, but what if I say that after reading this article you will be able to build the documentation of your code simply, beautiful and complete, that’s what we’ll see next

How to document

The documentation was in a summarized way, where you put the “///”, because their location will be responsible for saying what we are talking about, take the example:

The symbols “///” above a class or function mean that you are documenting it, that is, what is down.

So this documentation would look like this:

This works for the other functions:

Formatting:

Dart documenting accepts some Markdown type formatting if you don’t know what it’s like to access the link: https://www.markdownguide.org/getting-started/

Transforming from code to HTML

Now we come to the best part, where we will transform everything you wrote into a professional documentation equal to the official dart documentation.

After writing the meanings of classes, functions, and some variables, run the code:

Dartdoc .

If this command does not work, run the command:

Flutter pub global run dartdoc .

In some version flutter does not accept the dartdoc command. in these cases we suggest the second option.

NOTE: the “ . ” At the end of the command means to document all files, if you wanted to specify type:

Flutter pub global run dartdoc app/yourFile.dart

After running the flutter/dart command will generate all your documentation ready to be hosted on some server (if you wanted) or a Github Page that would be a great idea.

Running code

After running the code flutter will generate a folder called “doc” located at the root of the project, access it and you will have all its classes specified and a file containing all the documentation:

After finding the file containing all the documentation run:

Note: es installed the Live Preview extension that allows me to see HTML files within VsCode

And ready now your code is fully documented and professionally, liked the tool and you learn more about how to document by following the rules of dart, so go to:

Documentation rules : https://dart.dev/guides/language/effective-dart/documentation

How to generate documentation : https://dart.dev/tools/dart-doc