Comments.md

Comments are often used to add hints, notes, suggestions, or warnings to DScript code. They serve to make the code easier to read and understand.

DScript supports three types of comments:

Single line comments

Single-line comments start with two slashes (//) and marks all text following it on the same line as a comment.

// This is a valid single line comment
const x = 10; // This too
const y = 10 // This line will fail as the following semicolon is part of the comment, not the code ;

Multi-line comments

Comments can span multiple lines by using the multiple-line comment style. These comments start with /* and end with */. The text between those markers is the comment.

/* This is 
    a multiline comment */
const x = 10; /* They can be anywhere */
const x = /* even in the middle of an expression */ 10;

Doc Comments

Comments having a special form can be used to direct various tool to get more information from the source code elements. Such comments are a special form of multi-line comments that start with a slash and two asterisks (/**). They must immediately precede a user-defined type (such as an interface, union type, enum or type alias), a member (such as a property, enum member or function) that they annotate or a variable declaration.

Documentation comments support various tags (using @tagName syntax) to add more meaning to the code.

/**
  * Sample function that adds two numbers.
  * @param {left} - The left argument to be added 
  * @param {right} - The left argument to be added 
  * @returns {number} Sum of a and b
  */
function add(left: number, right: number) : number { 
    return left + right;
};

The following tags provide commonly used functionality in a user documentation (for the full list of tags see JsDoc standard).

Tag	Purpose
@author	Identify the author of an item.
@copyright	Document some copyright information.
@description	Describe a symbol.
@example	Provide an example of how to use a documented item.
@license	Identify the license that applies to this code.
@name	Document the name of an object.
@param	Document the parameter to a function.
@private	This symbol is meant to be private.
@returns	Document the return value of a function
@see	Refer to some other documentation for more information.
@summary	A shorter version of the full description.

Documentation comments can show up in the IDE's IntelliSense and used by the DSDoc tool.