Documentation Comments ​

Documentation comments (aka doc comments) are the standardized comment lines used when documenting Jule source code. With this standard, Jule code can be documented and read using a universal style.

Context Types of Doc Comments ​

Doc comments have different types of contexts for effective and organized documentation. These contexts make the documentation more structured and easier to read.

Main Documentation Scope ​

The main context contains the primary content of the documentation. It includes any subcontexts and outlines of the documentation.

Lists ​

Lists can only be used in the main context and cannot have sub-lists. Any type of list always appears in the main context. A list item is defined by the - character (ASCII code 45) and accepts a single line of content. Any new line signifies the end of a list item.

Grouped Documentation and Subscopes ​

Documentation in groups and subscopes is treated as a separate main scope for the documentation within the main scope, having its own subscopes.

Separator Line ​

It is an empty comment line. It is used to create content that helps with documentation, like a paragraph.

Writing Doc Comments ​

Doc comments are written only as single-line comments. Range comments are not considered as documentation comments in any way.

When writing documentation comments within the main scope, at most one ASCII whitespace can be used. If there is any whitespace, it is ignored. All space characters (such as ASCII whitespace or tabs) are considered as indentation.

The suggested documentation approach is to write the main scopes starting with a single whitespace, and indent each sub-scope with a tab.

Here is an example documentation that uses all context types as described:

//This is a main scope documentation line.
// This is a main scope documentation line too.
//
//	This is a subscope because it uses tab for indentation.
//		This is a subscope for a previous subscope because it uses 2 tab.
//		- Looks like-list item but JuleDoc handles as a text in this subscope.
//		- Looks like list-item but JuleDoc handles as a text in this subscope.
//
//- This is a list item.
// - This is a list item.

Documentation must always come before the definition it belongs to, and any spaces or invalid comments (such as range comments) will break the documentation sequence. Therefore, using a separator for spaces is recommended.

For example:

// This is a documentation comment.
// But it will not appear in the JuleDoc output.
// Because whitespace will break the documentation group.

// This line and following lines will be appear in the JuleDoc output.
// Foo is a type for a magical use case.
// Just used to make an example.
type Foo: int

Internal Doc Comments ​

If you are using JuleDoc and want to write comments that won't appear in the documentation output, you can use range comments before all the doc comments.

Although they are ignored, it is recommended to write range comments according to the doc comment rules as well.

For example:

/*
This is an internal comment.
Because written using range comments.
This part will be ignored from JuleDoc output.
*/
// Foo is a type for a magical use case.
// Just used to make an example.
type Foo: int

Variable Groups ​

In some cases, you may need to create a shared documentation for multiple variables. To do this, simply group the variables together. To group them, all you need to do is write them one below the other.

For example:

// This variables are for a magical use case.
// Just used to make an example.
const Foo = "foo"
const Bar = "bar" // Optional special inline comment for Bar.
const Baz = "baz" // Optional special inline comment for Baz.