What should a flutter app documentation look like?

Question

I have to comment / give a documentation for the app I created with flutter.

I've seen the DartDoc to generate a documentation. But this would only apply to the Dart code I have in my app, which mean basically the business logic. What about the UI ? What is the best way to comment the UI, or include it in the doc ?

Also, should a well documented app have only 'dartdoc comments' /// ? What is the role of basic comments // compared to dartcode comment ? Yes, it'll not appear in the doc, but how am I supposed to choose ?

Answer 1

Flutter code is not different to Dart code, other than it referencing the Flutter library. So, whether you want to use DartDoc or not, is up to you.

So the general rule of thumb is to:

• Use DartDoc comments to document code that you can access from other code (e.g. members and types, as recommended by the Effective Dart guide you've linked), especially since they allow you to go into detail (by adding rich content) with Markdown formatting provided by DartDoc.

• Use regular comments to document how your code works, e.g. inside a method.

A good library should have their exposed members/types documented, so other developers can catch on with its functionality quickly.

To conclude, the one does not exclude the other, no matter whether you're only using Dart or Dart+Flutter, you can also use regular comments and/or DartDoc comments to document your code.