Similar to Rust, comments starting with /// (three slashes) or /** (two asterisks) are doc-comments.

Doc-comments can only appear in front of function definitions, not any other elements:


#![allow(unused)]
fn main() {
/// This is a valid one-line doc-comment
fn foo() {}

/** This is a
** valid block
** doc-comment
**/
fn bar(x) {
/// Syntax error - this doc-comment is invalid
x + 1
}

/** Syntax error - this doc-comment is invalid */
let x = 42;

/// Syntax error - this doc-comment is also invalid
{
let x = 42;
}
}


## Special Cases

Long streams of //////... and /*****... do NOT form doc-comments. This is consistent with popular comment block styles for C-like languages.


#![allow(unused)]
fn main() {
///////////////////////////////  <- this is not a doc-comment
// This is not a doc-comment //  <- this is a normal comment
///////////////////////////////  <- this is not a doc-comment

// However, watch out for comment lines starting with '///'

//////////////////////////////////////////  <- this is not a doc-comment
/// This, however, IS a doc-comment!!! ///  <- this starts with '///'
//////////////////////////////////////////  <- this is not a doc-comment

/****************************************
*                                      *
* This is also not a doc-comment block *
* so we don't have to put this in      *
* front of a function.                 *
*                                      *
****************************************/
}


Doc-comments are stored within the script’s AST after compilation.
The AST::iter_functions method provides a ScriptFnMetadata instance for each function defined within the script, which includes doc-comments.
Doc-comments can be disabled via the Engine::set_doc_comments method.