Skip to content

Commit 88574fc

Browse files
author
John Kleint
committed
Show that Rust has range comments; doc comments as convention.
1 parent 9b98332 commit 88574fc

File tree

1 file changed

+24
-21
lines changed

1 file changed

+24
-21
lines changed

src/doc/guide.md

+24-21
Original file line numberDiff line numberDiff line change
@@ -822,28 +822,34 @@ that we haven't learned about yet, so let's just leave it at that for now.
822822
# Comments
823823

824824
Now that we have some functions, it's a good idea to learn about comments.
825-
Comments are notes that you leave to other programmers to help explain things
826-
about your code. The compiler mostly ignores them.
825+
Comments are notes that you leave to other programmers to help explain your code.
826+
The compiler ignores them.
827827

828-
Rust has two kinds of comments that you should care about: **line comment**s
829-
and **doc comment**s.
828+
Line comments start with `//` and extend to the end of the line.
830829

831830
```{rust}
832-
// Line comments are anything after '//' and extend to the end of the line.
831+
// Line comments are anything from '//' to the end of the line.
832+
let x = 5i; // This is also a line comment.
833+
```
833834

834-
let x = 5i; // this is also a line comment.
835+
Range comments start with `/*` and can span multiple lines; they end with `*/`.
835836

836-
// If you have a long explanation for something, you can put line comments next
837-
// to each other. Put a space between the // and your comment so that it's
838-
// more readable.
837+
```{rust}
838+
/* This is a range comment.
839+
Anything inside is ignored by the compiler.
840+
This lets you freely wrap comment text.
841+
*/
842+
let x = 42i; /* Range comments can also be a single line. */
839843
```
840844

841-
The other kind of comment is a doc comment. Doc comments use `///` instead of
842-
`//`, and support Markdown notation inside:
845+
By convention, a line comment starting with `///` or a range comment starting
846+
with `/**` is a **doc comment**. By formatting such comments with
847+
[Markdown](http://daringfireball.net/projects/markdown/), the `rustdoc` tool
848+
can automatically create HTML documentation for your code. Single-line
849+
comments are the preferred style.
843850

844-
```{rust}
845-
/// `hello` is a function that prints a greeting that is personalized based on
846-
/// the name given.
851+
````{rust}
852+
/// `hello` is a function that prints a personalized greeting.
847853
///
848854
/// # Arguments
849855
///
@@ -855,17 +861,14 @@ The other kind of comment is a doc comment. Doc comments use `///` instead of
855861
/// let name = "Steve";
856862
/// hello(name); // prints "Hello, Steve!"
857863
/// ```
864+
///
858865
fn hello(name: &str) {
859866
println!("Hello, {}!", name);
860867
}
861-
```
862-
863-
When writing doc comments, adding sections for any arguments, return values,
864-
and providing some examples of usage is very, very helpful.
868+
````
865869

866-
You can use the `rustdoc` tool to generate HTML documentation from these doc
867-
comments. We will talk more about `rustdoc` when we get to modules, as
868-
generally, you want to export documentation for a full module.
870+
When writing doc comments, adding sections for any arguments and return values
871+
is very helpful, as is providing some examples of usage.
869872

870873
# Compound Data Types
871874

0 commit comments

Comments
 (0)