---

yaml
---
r: 94186
b: refs/heads/try
c: ac4dd9e
h: refs/heads/master
v: v3

Author: bors

[refs]

@@ -2,7 +2,7 @@
 refs/heads/master: 0da105a8b7b6b1e0568e8ff20f6ff4b13cc7ecc2
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: a6d3e57dca68fde4effdda3e4ae2887aa535fcd6
-refs/heads/try: a16753c18844ad37d63ee00fe0292303afc990ac
+refs/heads/try: ac4dd9efee9248f4c3235460f3c93acc9932eb5a
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: 147ecfdd8221e4a4d4e090486829a06da1e0ca3c

branches/try/doc/rustdoc.md

@@ -0,0 +1,72 @@
+% Rust Documentation
+
+`rustdoc` is the built-in tool for generating documentation. It integrates
+with the compiler to provide accurate hyperlinking between usage of types and
+their documentation. Furthermore, by not using a separate parser, it will
+never reject your valid Rust code.
+
+# Creating Documentation
+
+Documenting Rust APIs is quite simple. To document a given item, we have "doc
+comments":
+
+~~~
+// the "link" crate attribute is currently required for rustdoc, but normally
+// isn't needed.
+#[link(name="universe")];
+#[crate_type="lib"];
+
+//! Tools for dealing with universes (this is a doc comment, and is shown on
+//! the crate index page. The ! makes it apply to the parent of the comment,
+//! rather than what follows).
+
+/// Widgets are very common (this is a doc comment, and will show up on
+/// Widget's documentation).
+pub struct Widget {
+	/// All widgets have a purpose (this is a doc comment, and will show up
+	/// the field's documentation).
+	purpose: ~str,
+	/// Humans are not allowed to understand some widgets
+	understandable: bool
+}
+
+pub fn recalibrate() {
+	//! Recalibrate a pesky universe (this is also a doc comment, like above,
+	//! the documentation will be applied to the *parent* item, so
+	//! `recalibrate`).
+	/* ... */
+}
+~~~
+
+Then, one can run `rustdoc universe.rs`. By default, it generates a directory
+called `doc`, with the documentation for `universe` being in
+`doc/universe/index.html`. If you are using other crates with `extern mod`,
+rustdoc will even link to them when you use their types, as long as their
+documentation has already been generated by a previous run of rustdoc, or the
+crate advertises that its documentation is hosted at a given URL.
+
+The generated output can be controlled with the `doc` crate attribute, which
+is how the above advertisement works. An example from the `libstd`
+documentation:
+
+~~~
+#[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
+      html_favicon_url = "http://www.rust-lang.org/favicon.ico",
+      html_root_url = "http://static.rust-lang.org/doc/master")];
+~~~
+
+The `html_root_url` is the prefix that rustdoc will apply to any references to
+that crate's types etc.
+
+rustdoc can also generate JSON, for consumption by other tools, with
+`rustdoc --output-format json`, and also consume already-generated JSON with
+`rustdoc --input-format json`.
+
+# Using the Documentation
+
+The web pages generated by rustdoc present the same logical heirarchy that one
+writes a library with. Every kind of item (function, struct, etc) has its own
+color, and one can always click on a colored type to jump to its
+documentation. There is a search bar at the top, which is powered by some
+javascript and a statically-generated search index. No special web server is
+required for the search.

branches/try/doc/tutorial-ffi.md

@@ -152,7 +152,7 @@ for the rust task is plenty for the C function to have.
 
 A planned future improvement (net yet implemented at the time of this writing)
 is to have a guard page at the end of every rust stack. No rust function will
-hit this guard page (due to rust's usage of LLVM's __morestack). The intention
+hit this guard page (due to Rust's usage of LLVM's `__morestack`). The intention
 for this unmapped page is to prevent infinite recursion in C from overflowing
 onto other rust stacks. If the guard page is hit, then the process will be
 terminated with a message saying that the guard page was hit.
@@ -166,30 +166,39 @@ the stack of the task which is spawned.
 
 # Destructors
 
-Foreign libraries often hand off ownership of resources to the calling code,
-which should be wrapped in a destructor to provide safety and guarantee their
-release.
+Foreign libraries often hand off ownership of resources to the calling code.
+When this occurs, we must use Rust's destructors to provide safety and guarantee
+the release of these resources (especially in the case of failure).
 
-A type with the same functionality as owned boxes can be implemented by
-wrapping `malloc` and `free`:
+As an example, we give a reimplementation of owned boxes by wrapping `malloc`
+and `free`:
 
 ~~~~
 use std::cast;
 use std::libc::{c_void, size_t, malloc, free};
 use std::ptr;
 use std::unstable::intrinsics;
 
-// a wrapper around the handle returned by the foreign code
+// Define a wrapper around the handle returned by the foreign code.
+// Unique<T> has the same semantics as ~T
 pub struct Unique<T> {
+    // It contains a single raw, mutable pointer to the object in question.
     priv ptr: *mut T
 }
 
+// Implement methods for creating and using the values in the box.
+// NB: For simplicity and correctness, we require that T has kind Send
+// (owned boxes relax this restriction, and can contain managed (GC) boxes).
+// This is because, as implemented, the garbage collector would not know
+// about any shared boxes stored in the malloc'd region of memory.
 impl<T: Send> Unique<T> {
     pub fn new(value: T) -> Unique<T> {
         unsafe {
             let ptr = malloc(std::mem::size_of::<T>() as size_t) as *mut T;
             assert!(!ptr::is_null(ptr));
             // `*ptr` is uninitialized, and `*ptr = value` would attempt to destroy it
+            // move_val_init moves a value into this memory without
+            // attempting to drop the original value.
             intrinsics::move_val_init(&mut *ptr, value);
             Unique{ptr: ptr}
         }
@@ -206,12 +215,20 @@ impl<T: Send> Unique<T> {
     }
 }
 
+// The key ingredient for safety, we associate a destructor with
+// Unique<T>, making the struct manage the raw pointer: when the
+// struct goes out of scope, it will automatically free the raw pointer.
+// NB: This is an unsafe destructor, because rustc will not normally
+// allow destructors to be associated with parametrized types, due to
+// bad interaction with managed boxes. (With the Send restriction,
+// we don't have this problem.)
 #[unsafe_destructor]
 impl<T: Send> Drop for Unique<T> {
     fn drop(&mut self) {
         unsafe {
-            let x = intrinsics::init(); // dummy value to swap in
-            // moving the object out is needed to call the destructor
+            let x = intrinsics::uninit(); // dummy value to swap in
+            // We need to move the object out of the box, so that
+            // the destructor is called (at the end of this scope.)
             ptr::replace_ptr(self.ptr, x);
             free(self.ptr as *c_void)
         }

branches/try/doc/tutorial-rustpkg.md

@@ -198,7 +198,7 @@ Now you can install and use it! Go anywhere else in your filesystem:
 
 ~~~ {.notrust}
 $ cd ~/src/foo
-$ rustpkg install github/YOUR_USERNAME/hello
+$ rustpkg install github.com/YOUR_USERNAME/hello
 WARNING: The Rust package manager is experimental and may be unstable
 note: Installed package github.com/YOUR_USERNAME/hello-0.1 to /home/yourusername/src/hello/.rust
 ~~~