How to effectively generate documentation from your code base in your project

Riverpod Example: Generated documentation from code base

If there is a documentation writer in your company, do you feel the questions from the writer is very simple but wasting your time? If you are the developer, are you struggling on writing documentation and spending a log of time to manage and maintain it. If you are a team leader, do you have this situation, when you open the code documentation, but it haven’t been updated for a year, or some of the class or function doesn’t have documentation? Why don’t we create the documentation from the code base? Dart Documentation is always there ready for all developers to use in your project.

When we work on large projects, we tend to spend a lot of time managing the documentation aspects of the project. Dart Document is a tool that can help developers and companies to organize documentation in a better way for their projects. Documentation plays a crucial role in any project, and for large scale projects, it becomes extremely important. Dart Document helps you to manage and organize your documentation seamlessly.

Dart Document provides a web-based platform where you can create, manage, and publish documentation for your project. It is built on top of Dart-Doc, which is a tool for generating API documentation. With Dart Document, you can create rich content and easily organize your documentation using a simple directory structure. You don’t have to worry about creating documentation from scratch, Dart Document provides pre-built themes that make your documentation appealing and professional.

Dart Document is also customizable, which means you can customize it to meet your project’s unique requirements. You can add your logo, change the theme, and customize the CSS to match your branding.

Dart Document also makes it easier for developers to get started with a new project. It is easy to set up, and you can start documenting your project immediately. You can easily integrate your documentation with external sources such as GitHub and GitLab, which makes it easier to collaborate with other team members and share your documentation.

How to use it and get all developer invole to documentations

1. Add 2 main lint rules into the analysis_options.yaml file in your project

• package_api_docs
• public_member_api_docs

Once added in these 2 lint rule, you can see a blue wavy line under the class name. When you put your mouse on the class name, you can see the message like the following info.

By this way, when the developers create a public class in the project, it will notice the developer to write comments for this class. When we do the code review in pr, we can require the developer add in the documentation. As the developer created this class, he is the most familar with this class, why we create it, what tasks it does, how to use it.

2. To generate a beautiful documentation, we need to follow some other rules

It is too many rules, so I just outline the title here. You can open the details by clicking on the link below.

Libraries

• DO use strings in part of directives
• DON’T import libraries that are inside the src directory of another package
• DON’T allow an import path to reach into or out of lib
• PREFER relative import paths

Null

• DON’T explicitly initialize variables to null
• DON’T use an explicit default value of null
• DON’T use true or false in equality operations
• AVOID late variables if you need to check whether they are initialized
• CONSIDER assigning a nullable field to a local variable to enable type promotion

Strings

• DO use adjacent strings to concatenate string literals
• PREFER using interpolation to compose strings and values
• AVOID using curly braces in interpolation when not needed

Collections

• DO use collection literals when possible
• DON’T use .length to see if a collection is empty
• AVOID using Iterable.forEach() with a function literal
• DON’T use List.from() unless you intend to change the type of the result
• DO use whereType() to filter a collection by type
• DON’T use cast() when a nearby operation will do
• AVOID using cast()

Functions

• DO use a function declaration to bind a function to a name
• DON’T create a lambda when a tear-off will do
• DO use = to separate a named parameter from its default value

Variables

• DO follow a consistent rule for var and final on local variables
• AVOID storing what you can calculate

Members

• DON’T wrap a field in a getter and setter unnecessarily
• PREFER using a final field to make a read-only property
• CONSIDER using => for simple members
• DON’T use this. except to redirect to a named constructor or to avoid shadowing
• DO initialize fields at their declaration when possible

Constructors

• DO use initializing formals when possible
• DON’T use late when a constructor initializer list will do
• DO use ; instead of {} for empty constructor bodies
• DON’T use new
• DON’T use const redundantly

Error handling

• AVOID catches without on clauses
• DON’T discard errors from catches without on clauses
• DO throw objects that implement Error only for programmatic errors
• DON’T explicitly catch Error or types that implement it
• DO use rethrow to rethrow a caught exception

Asynchrony

• PREFER async/await over using raw futures
• DON’T use async when it has no useful effect
• CONSIDER using higher-order methods to transform a stream
• AVOID using Completer directly
• DO test for Future<T> when disambiguating a FutureOr<T> whose type argument could be Object

3. How to generate the documentation

As long as you wrote the proper comments in the code base, it will be very easy to generate the documentation.

dart doc .

We just need to go to your root directory of your project, runs the above cmd, and dart will generate a folder call doc/api, and this is a web base documentation with an index.html file. You can open it on any web browser and it is easy to host the documentation on github or some other host.

Conclusion

In conclusion, Dart Document is a tool that every developer should consider using in their projects. It streamlines the documentation aspect of the project, making it easier for developers to manage and organize their documentation effectively. With Dart Document, you can create professional, appealing documentation using pre-built themes and easily collaborate with team members. The tool is easy to set up, and customization options give you the freedom to create a unique documentation experience. If you haven’t used Dart Document before, now is the time to give it a try and witness the benefits it brings to your projects.