diff --git a/doc/tutorial-ffi.md b/doc/tutorial-ffi.md index b7e39390168..92ba09856b0 100644 --- a/doc/tutorial-ffi.md +++ b/doc/tutorial-ffi.md @@ -1,4 +1,6 @@ -# Interacting with foreign code +% Rust Foreign Function Interface Tutorial + +# Introduction One of Rust's aims, as a system programming language, is to interoperate well with C code. @@ -38,7 +40,7 @@ fn main(args: ~[~str]) { } ~~~~ -## Foreign modules +# Foreign modules Before we can call `SHA1`, we have to declare it. That is what this part of the program is responsible for: @@ -68,7 +70,7 @@ extern mod something { } ~~~~ -## Foreign calling conventions +# Foreign calling conventions Most foreign code will be C code, which usually uses the `cdecl` calling convention, so that is what Rust uses by default when calling foreign @@ -88,7 +90,7 @@ The `"abi"` attribute applies to a foreign module (it can not be applied to a single function within a module), and must be either `"cdecl"` or `"stdcall"`. Other conventions may be defined in the future. -## Unsafe pointers +# Unsafe pointers The foreign `SHA1` function is declared to take three arguments, and return a pointer. @@ -118,7 +120,7 @@ caution—unlike Rust's other pointer types, unsafe pointers are completely unmanaged, so they might point at invalid memory, or be null pointers. -## Unsafe blocks +# Unsafe blocks The `sha1` function is the most obscure part of the program. @@ -159,7 +161,7 @@ unsafe fn kaboom() { ~"I'm harmless!"; } This function can only be called from an unsafe block or another unsafe function. -## Pointer fiddling +# Pointer fiddling The standard library defines a number of helper functions for dealing with unsafe data, casting between types, and generally subverting @@ -202,7 +204,7 @@ unsafe pointer that was returned by `SHA1`. SHA1 digests are always twenty bytes long, so we can pass `20u` for the length of the new vector. -## Passing structures +# Passing structures C functions often take pointers to structs as arguments. Since Rust structs are binary-compatible with C structs, Rust programs can call diff --git a/doc/tutorial-macros.md b/doc/tutorial-macros.md index deb6252d042..5cd5d79bd29 100644 --- a/doc/tutorial-macros.md +++ b/doc/tutorial-macros.md @@ -1,4 +1,6 @@ -# Macros +% Rust Macros Tutorial + +# Introduction Functions are the programmer's primary tool of abstraction, but there are cases in which they are insufficient, because the programmer wants to @@ -50,7 +52,7 @@ early_return!(input_2 special_b); Macros are defined in pattern-matching style: -## Invocation syntax +# Invocation syntax On the left-hand-side of the `=>` is the macro invocation syntax. It is free-form, excepting the following rules: @@ -69,7 +71,7 @@ rules of tokenization apply, So `($x:ident => (($e:expr)))`, though excessively fancy, would create a macro that could be invoked like `my_macro!(i=>(( 2+2 )))`. -## Transcription syntax +# Transcription syntax The right-hand side of the `=>` follows the same rules as the left-hand side, except that `$` need only be followed by the name of the syntactic fragment @@ -80,9 +82,9 @@ an expression; currently, user-defined macros can only be invoked in expression position (even though `macro_rules!` itself can be in item position). -## Multiplicity +# Multiplicity -### Invocation +## Invocation Going back to the motivating example, suppose that we wanted each invocation of `early_return` to potentially accept multiple "special" identifiers. The diff --git a/doc/tutorial-tasks.md b/doc/tutorial-tasks.md index 2f540ef9ee6..195f3d0bcc8 100644 --- a/doc/tutorial-tasks.md +++ b/doc/tutorial-tasks.md @@ -1,4 +1,6 @@ -% Tasks and communication in Rust +% Rust Tasks and Communication Tutorial + +# Introduction Rust supports a system of lightweight tasks, similar to what is found in Erlang or other actor systems. Rust tasks communicate via messages