reorganize module

_archive/rhai_engine/rhaibook/ref/comments.md

@@ -0,0 +1,113 @@
+Comments
+========
+
+Comments are C-style, including `/*` ... `*/` pairs for block comments and `//` for comments to the
+end of the line.
+
+Block comments can be nested.
+
+```rust
+let /* intruder comment */ name = "Bob";
+
+// This is a very important one-line comment
+
+/* This comment spans
+   multiple lines, so it
+   only makes sense that
+   it is even more important */
+
+/* Fear not, Rhai satisfies all nesting needs with nested comments:
+   /*/*/*/*/**/*/*/*/*/
+*/
+```
+
+
+Doc-Comments
+============
+
+Comments starting with `///` (three slashes) or `/**` (two asterisks) are _doc-comments_.
+
+Doc-comments can only appear in front of [function](functions.md) definitions, not any other elements.
+
+```rust
+/// 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;
+}
+```
+
+
+~~~admonish tip "Tip: Special cases"
+
+Long streams of `//////`... and `/*****`... do _NOT_ form doc-comments.
+This is consistent with popular comment block styles for C-like languages.
+
+```rust
+///////////////////////////////  <- this is not a doc-comment
+// This is not a doc-comment //  <- this is not a doc-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!!! ///  <- doc-comment!
+//////////////////////////////////////////  <- 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.                 *
+ *                                      *
+ ****************************************/
+```
+~~~
+
+
+Module Documentation
+====================
+
+Comment lines starting with `//!` make up the _module documentation_.
+
+They are used to document the containing [module](modules/index.md) &ndash;
+or for a Rhai script file, to document the file itself.
+
+```rust
+//! Documentation for this script file.
+//! This script is used to calculate something and display the result.
+
+fn calculate(x) {
+   ...
+}
+
+fn display(msg) {
+   //! Module documentation can be placed anywhere within the file.
+   ...
+}
+
+//! All module documentation lines will be collected into a single block.
+```
+
+For the example above, the module documentation block is:
+
+```rust
+//! Documentation for this script file.
+//! This script is used to calculate something and display the result.
+//! Module documentation can be placed anywhere within the file.
+//! All module documentation lines will be collected into a single block.
+```