Add documentation.

Makefile

@@ -1,5 +1,6 @@
 kiss3d_lib_path=lib
 kiss3d_bin_path=bin
+kiss3d_doc_path=doc
 glfw_lib_path=glfw-rs/lib
 glcore_lib_path=glcore-rs/lib
 nalgebra_lib_path=nalgebra/lib
@@ -21,10 +22,16 @@ test:
 	$(build_cmd) src/demo/primitives_scale.rs 
 	$(build_cmd) src/demo/texturing.rs 
 
+doc:
+	mkdir -p $(kiss3d_doc_path)
+	rust doc src/kiss3d.rc --output-dir $(kiss3d_doc_path)
+
 deps:
 	make -C glfw-rs
 	make -C glcore-rs
 	make -C nalgebra
 	cd rust-stb-image; ./configure
 	make clean -C rust-stb-image
 	make -C rust-stb-image
+
+.PHONY:doc

doc/rust.css

@@ -0,0 +1,156 @@
+body {
+    padding: 1em 6em;
+    margin: 0;
+    margin-bottom: 4em;
+    font-family: "Helvetica Neue", Helvetica, sans-serif;
+    font-size: 12pt;
+    background-color: white;
+    color: black;
+    line-height: 1.6em;
+    min-width: 45em;
+    max-width: 60em;
+}
+
+h1 {
+    font-size: 24pt;
+    margin-top: 1.6em;
+    padding-left: 0.4em;
+    line-height: 1.6em;
+    background-color:#FFF2CE;
+    border-radius: 0.2em;
+}
+
+h2 {
+    font-size: 16pt;
+    margin-top: 1.6em;
+    padding: 0.2em 0.5em;
+    background-color:#FFF2CE;
+    border-radius: 0.4em;
+}
+
+h2 code {
+    color: #097334;
+    font-size: 16pt;
+}
+
+h3 {
+    font-size: 14pt;
+    color: black;
+    background-color:#D9E7FF;
+    border-radius: 0.4em;
+    padding: 0.2em 0.5em;
+}
+
+h3 code {
+    color: #541800;
+    font-size: 14pt;
+    font-style: italic;
+}
+
+h4 {
+    font-size: 11pt;
+    margin-top: 0em;
+    margin-bottom: 0em;
+}
+
+code {
+    font-size: 11pt;
+}
+
+pre {
+    margin-left: 1.1em;
+    padding: .4em .4em .4em .8em;
+    font-size: 10pt;
+    background-color: #F5F5F5;
+    border-radius: 0.5em;
+    border: 1px solid rgba(0, 0, 0, 0.15);
+}
+
+pre.rust {
+    background-color: #F3F6FF;
+}
+
+a, a:visited, a:link {
+    text-decoration: none;
+    color: rgb(0, 105, 214);
+}
+
+h1 a:link, h1 a:visited, h2 a:link, h2 a:visited,
+h3 a:link, h3 a:visited { color: black; }
+
+/* Code highlighting */
+.cm-s-default span.cm-keyword {color: #708;}
+.cm-s-default span.cm-atom {color: #219;}
+.cm-s-default span.cm-number {color: #164;}
+.cm-s-default span.cm-def {color: #00f;}
+.cm-s-default span.cm-variable {color: black;}
+.cm-s-default span.cm-variable-2 {color: #05a;}
+.cm-s-default span.cm-variable-3 {color: #085;}
+.cm-s-default span.cm-property {color: black;}
+.cm-s-default span.cm-operator {color: black;}
+.cm-s-default span.cm-comment {color: #a50;}
+.cm-s-default span.cm-string {color: #a11;}
+.cm-s-default span.cm-string-2 {color: #f50;}
+.cm-s-default span.cm-meta {color: #555;}
+.cm-s-default span.cm-error {color: #f00;}
+.cm-s-default span.cm-qualifier {color: #555;}
+.cm-s-default span.cm-builtin {color: #30a;}
+.cm-s-default span.cm-bracket {color: #cc7;}
+.cm-s-default span.cm-tag {color: #170;}
+.cm-s-default span.cm-attribute {color: #00c;}
+
+#versioninfo {
+  position: fixed;
+  bottom: 0px;
+  right: 0px;
+
+  background-color: white;
+  padding: 0.5em;
+}
+
+a.lessimportant {
+  color: gray;
+  font-size: 60%;
+}
+
+blockquote {
+    color: black;
+    border-left: solid 1px silver;
+    margin: 1em;
+    padding: 0.5em 1em 0.5em 1em;
+}
+
+/* Make the table under the tutorial's 'Types' section look nicer */
+table {
+    border-top: 1px solid silver;
+    border-bottom: 1px solid silver;
+    padding: 0.8em;
+    font-size: smaller;
+}
+/* Also for the benefit of the type table */
+td {
+    padding-right: 1em;
+}
+
+/* Only display one level of hierarchy in the TOC */
+#TOC ul ul {
+    display: none;
+}
+
+#TOC ul {
+    list-style: none;
+    padding-left: 0px;
+}
+
+/* Adjust list alignment so rustdoc indexes don't align with blockquotes */
+div.index ul {
+    padding-left: 1em;
+}
+
+ul {
+    margin-top: 0em
+}
+
+div.section.level3  {
+    margin-left: 1.0em;
+}

src/arc_ball.rs

@@ -7,21 +7,37 @@ use nalgebra::vec::Vec3;
 use glfw::consts::*;
 use event;
 
+/// Arc-ball camera mode. An arc-ball camera is a camera rotating around a fixed point (the focus
+/// point) and always looking at it. The following inputs are handled:
+///
+///   * Left button press + drag - rotates the camera around the focus point
+///   * Right button press + drag - translates the focus point on the plane orthogonal to the view
+///   direction
+///   * Scroll in/out - zoom in/out
+///   * Enter key - set the focus point to the origin
 #[deriving(Clone, ToStr)]
 pub struct ArcBall
 {
+  /// The focus point.
   at:    Vec3<f64>,
+  /// Yaw of the camera (rotation along the y axis).
   yaw:   f64,
+  /// Pitch of the camera (rotation along the x axis).
   pitch: f64,
+  /// Distance from the camera to the `at` focus point.
   dist:  f64,
 
+  /// Increment of the yaw per unit mouse movement. The default value is 0.005.
   yaw_step:   f64,
+  /// Increment of the pitch per unit mouse movement. The default value is 0.005.
   pitch_step: f64,
+  /// Increment of the distance per unit scrolling. The default value is 40.0.
   dist_step:  f64,
 }
 
 impl ArcBall
 {
+  /// Creates a new arc ball camera with default sensitivity values.
   pub fn new() -> ArcBall
   {
     ArcBall {
@@ -35,12 +51,14 @@ impl ArcBall
     }
   }
 
+  /// Changes the orientation and position of the arc-ball to look at the specified point.
   pub fn look_at(&mut self, _: Vec3<f64>, at: Vec3<f64>)
   {
     self.at = at;
     fail!("Not yet implemented.");
   }
 
+  /// The camera actual transformation.
   pub fn transformation(&self) -> Iso3f64
   {
     let mut id = One::one::<Iso3f64>();
@@ -49,6 +67,7 @@ impl ArcBall
     id
   }
 
+  /// The position of the camera.
   pub fn eye(&self) -> Vec3<f64>
   {
     let px = self.at.x + self.dist * self.yaw.cos() * self.pitch.sin();
@@ -58,7 +77,7 @@ impl ArcBall
     Vec3::new(px, py, pz)
   }
 
-  pub fn update_restrictions(&mut self)
+  fn update_restrictions(&mut self)
   {
     if (self.dist < 0.00001)
     { self.dist = 0.00001 }
@@ -70,6 +89,7 @@ impl ArcBall
     { self.pitch = Real::pi::<f64>() - 0.0001 }
   }
 
+  #[doc(hidden)]
   pub fn handle_left_button_displacement(&mut self, dx: float, dy: float)
   {
     self.yaw   = self.yaw   + dx as f64 * self.yaw_step;
@@ -78,6 +98,7 @@ impl ArcBall
     self.update_restrictions();
   }
 
+  #[doc(hidden)]
   pub fn handle_right_button_displacement(&mut self, dx: float, dy: float)
   {
     let eye       = self.eye();
@@ -91,12 +112,14 @@ impl ArcBall
                       + bitangent.scalar_mul(&(dy as f64 * mult))
   }
 
+  #[doc(hidden)]
   pub fn handle_scroll(&mut self, yoff: float)
   {
     self.dist = self.dist + self.dist_step * (yoff as f64) / 120.0;
     self.update_restrictions();
   }
 
+  #[doc(hidden)]
   pub fn handle_keyboard(&mut self, event: &event::KeyboardEvent)
   {
     match *event

src/camera.rs

@@ -27,6 +27,7 @@ pub enum CameraMode
   FPS
 }
 
+/// Structure representing the camera.
 pub struct Camera
 {
   priv changed:       bool,
@@ -37,6 +38,7 @@ pub struct Camera
 
 impl Camera
 {
+  #[doc(hidden)]
   pub fn new(mode: CameraMode) -> Camera
   {
     Camera {
@@ -47,16 +49,20 @@ impl Camera
     }
   }
 
+  /// Modify the camera mode. Any modifications will be taken in account during the nexit display
+  /// loop.
   pub fn change_mode<'r>(&'r mut self, f: &fn(&'r mut CameraMode))
   {
     f(&'r mut self.mode);
 
     self.changed = true;
   }
 
+  /// The current camera mode.
   pub fn mode(&self) -> CameraMode
   { self.mode }
 
+  #[doc(hidden)]
   pub fn handle_mouse(&mut self, event: &event::MouseEvent)
   {
     match *event
@@ -112,6 +118,7 @@ impl Camera
     self.changed = true;
   }
 
+  #[doc(hidden)]
   pub fn handle_keyboard(&mut self, event: &event::KeyboardEvent)
   {
     match self.mode
@@ -120,10 +127,13 @@ impl Camera
         ab.handle_keyboard(event);
         self.changed = true;
       },
-      FPS                 => fail!("FPS mode not yet implemented.")
+      FPS => fail!("FPS mode not yet implemented.")
     }
   }
 
+  /// The transformation of the camera. This corresponds to the position and orientation of the
+  /// camera. Note that this is not the projection used as the view matrix. The view matrix is the
+  /// inverse of this matrix.
   pub fn transformation(&self) -> Iso3f64
   {
     match self.mode
@@ -133,6 +143,7 @@ impl Camera
     }
   }
 
+  #[doc(hidden)]
   pub fn upload(&mut self, view_location: i32)
   {
     if self.changed // do not reupload if nothing changed

src/kiss3d.rc

@@ -3,7 +3,11 @@
        , author = "Sébastien Crozet"
        , uuid   = "0914a60f-37cd-40dc-9779-d72f237d99cc")];
 #[crate_type = "lib"];
-#[warn(non_camel_case_types)]
+#[deny(non_camel_case_types)];
+#[deny(non_uppercase_statics)];
+#[deny(unnecessary_qualification)];
+#[deny(missing_doc)];
+#[deny(warnings)];
 
 
 extern mod std;

src/obj.rs

@@ -22,6 +22,14 @@ type Texture = Vec2<GLfloat>;
 fn error(line: uint, err: &str) -> !
 { fail!("At line " + line.to_str() + ": " + err) }
 
+/// Parses a string representing an obj file and returns (vertices, normals, texture coordinates, indices)
+/// This is a very simple parser which only extracts vertices, normals, texture coordinates and
+/// indices. There are a lot of restriction on the format:
+///   * faces must have exactly three vertices (i-e faces must be triangulated by the exporter)
+///   * vertices informations on face declaration must have informations about the vertex, the
+///   normal and the texture coordinates (eg. `f 1/3/5 1/5/6 4/6/2`). If at least one is missing, the
+///   parsing will fail (eg. `f 1//0 2 3/5` will fail).
+/// Any line other than `f`, `v`, `vn`, `vt` is ignored by the parser.
 pub fn parse(string: &str) -> (~[GLfloat], ~[GLfloat], ~[GLfloat], ~[GLuint])
 {
   let mut vertices: ~[Vertex]  = ~[];