Dart - Comments

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

It improves the maintenance & readaibility for 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 a 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 the following tags

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) {
  ... logic for empty 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 to generates the Documentation.

It generates documentation and outputs 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