@@ -822,28 +822,34 @@ that we haven't learned about yet, so let's just leave it at that for now.
822
822
# Comments
823
823
824
824
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.
827
827
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.
830
829
831
830
``` {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
+ ```
833
834
834
- let x = 5i; // this is also a line comment .
835
+ Range comments start with ` /* ` and can span multiple lines; they end with ` */ ` .
835
836
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. */
839
843
```
840
844
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.
843
850
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.
847
853
///
848
854
/// # Arguments
849
855
///
@@ -855,17 +861,14 @@ The other kind of comment is a doc comment. Doc comments use `///` instead of
855
861
/// let name = "Steve";
856
862
/// hello(name); // prints "Hello, Steve!"
857
863
/// ```
864
+ ///
858
865
fn hello(name: &str) {
859
866
println!("Hello, {}!", name);
860
867
}
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
+ ````
865
869
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.
869
872
870
873
# Compound Data Types
871
874
0 commit comments