Comments are a useful description of line or block code that helps developers to understand the code better.

It improves maintenance of the code to easy for multiple developers.

A Dart and Flutter programming language supports various comment types.

  • Single line and inline comments
  • Multiline or block line comments
  • Documentation comments.

Comments text is ignored by the compiler and it does not generate in byte code.

How to write a single-line comment in Dart?

Single-line comments are added as a new line or inline to code.

Single-line Comments always start with a double forward slash // symbol followed by text content.

Syntax:

// Single line comment example

Here is a Dart single line comment example

// Hello World Example
void main() {
  print("Comment example"); // Print text string to console
}

Dart multiline comments

Comments text does span in multiple lines, These are also called block-level comments.

These comments start with /* and are followed by the text content in multiple lines, ending with */. Here is a syntax example

/*
*
* multi-line comment line1
* multi-line comment line2
*/

Here is an example

/*
* Hello world example code
* Helloworld.dart file
*/
void main() {
/* print text string to console
 * print is an built function
 */
  print("Comment example");
}

How to write and parse documentation comments?

Every program provides documentation for API and an end-user guide for understanding the code.

Dart provides special comments syntax for writing documentation comments in the code using square brackets for identifiers and @ for tag syntax

It provides rich documentation tags for functions, classes, and interfaces using the @ syntax format.

dart doc reads dart source code and generates Documentation Comments.

It helps the user to develop documentation.

These can be included with single or multiple-line comments.

  • Single line comments three double slashes(///) C# Style
  • Multiple line comments start with /* and end with */ java code comment styles, Not recommended

It contains following tags

tags Description used
@param parameter for a function Class, and interface
@author Author name for Classes and files class or interface, function
@throws Specify an error thrown by function class or interface, function
@return return types of an function function

Here is a documentation comments example

/// __isEmpty__ method.
/// Checks for empty or null for a given string.
/// Examples
/// ```dart
/// isEmpty(null) == true
/// isEmpty("") == true
/// isEmpty("one") == false
/// ```
/// @param string The given input string
/// @returns A boolean The true or false values.


void isEmpty(String string) {
  ...
}

Once you have the comments ready, we have to run the following command

A:\work\dart>dart doc .
Documenting mydartapp...

Success! Docs generated into A:\work\dart/mydartapp/doc/api

doc is a dart parser used

It generates documentation and output HTML files in doc/api folder.

Notes:

  • It is best to use to /// syntax than /* */ syntax in readability
  • First, always tell about single-line description
  • These comments always start with capitalizing the first-word letter of every line
  • It includes markdown content for styling the comments
  • Code Syntax blocks can be included in Comments
  • square brackets for linking identifier