slight doc improvements

src/callbacks.rs

@@ -176,13 +176,14 @@ pub trait JackHandler: Send + Sync {
     fn latency(&self, _mode: LatencyType) {}
 }
 
+/// Wrap a closure that can handle the `process` callback. This is called every time data from ports
+/// is available from JACK.
 pub struct ProcessHandler<F: 'static + Send + FnMut(&ProcessScope) -> JackControl> {
     pub process: F,
 }
 
 unsafe impl<F: 'static + Send + FnMut(&ProcessScope) -> JackControl> Sync for ProcessHandler<F> {}
 
-
 impl<F: 'static + Send + FnMut(&ProcessScope) -> JackControl> JackHandler for ProcessHandler<F> {
     #[allow(mutable_transmutes)]
     fn process(&self, ps: &ProcessScope) -> JackControl {
@@ -328,14 +329,16 @@ unsafe extern "C" fn latency<T: JackHandler>(mode: j::jack_latency_callback_mode
     obj.0.latency(mode)
 }
 
-/// Clears the callbacks registered to `client`.
+/// Unsafe ffi wrapper that clears the callbacks registered to `client`.
 ///
 /// Returns `Err(JackErr::CallbackDeregistrationError)` on failure.
 ///
 /// # Unsafe
+///
 /// * Uses ffi calls, be careful.
 ///
 /// # TODO
+///
 /// * Implement correctly. Freezes on my system.
 pub unsafe fn clear_callbacks(_client: *mut j::jack_client_t) -> Result<(), JackErr> {
     // j::jack_set_thread_init_callback(client, None, ptr::null_mut());
@@ -357,10 +360,13 @@ pub unsafe fn clear_callbacks(_client: *mut j::jack_client_t) -> Result<(), Jack
 /// client.
 ///
 /// # TODO
+///
 /// * Handled failed registrations
 /// * Fix `jack_set_port_rename_callback`
 ///
 /// # Unsafe
+///
+/// * makes ffi calls
 /// * `handler` will not be automatically deallocated.
 pub unsafe fn register_callbacks<T: JackHandler>
     (handler: T,

src/lib.rs

@@ -5,7 +5,7 @@ extern crate jack_sys;
 extern crate lazy_static;
 extern crate libc;
 
-/// Defines callback traits and `ProcessScope`.
+/// Defines callback handlers and traits.
 pub mod callbacks;
 
 /// Create a connection to a JACK server.
@@ -39,10 +39,10 @@ pub mod traits {
 
 /// Contains most functionality to interact with JACK.
 pub mod prelude {
-    pub use callbacks::{JackHandler, ProcessHandler, ProcessScope};
+    pub use callbacks::*;
     pub use client::*;
-    pub use logging::*;
     pub use jack_enums::*;
+    pub use logging::*;
     pub use port::*;
     pub use primitive_types::*;
 }

src/port/mod.rs

@@ -1,9 +1,11 @@
 mod audio;
 mod midi;
 mod port;
+
+/// Contains flag constants that may be used to create `PortFlags`.
 pub mod port_flags;
 
 pub use self::port::*;
-pub use self::audio::{AudioInSpec, AudioInPort, AudioOutSpec, AudioOutPort};
-pub use self::midi::{MidiInSpec, MidiInPort, MidiIter, MidiOutSpec, MidiOutPort, RawMidi};
+pub use self::audio::{AudioInPort, AudioInSpec, AudioOutPort, AudioOutSpec};
+pub use self::midi::{MidiInPort, MidiInSpec, MidiIter, MidiOutPort, MidiOutSpec, RawMidi};
 pub use self::port_flags::PortFlags;

src/port/port.rs

@@ -241,14 +241,17 @@ pub struct Unowned;
 pub type UnownedPort = Port<Unowned>;
 
 unsafe impl PortSpec for Unowned {
+    /// Panics on call since the `Unowned` spec can't be used to create ports.
     fn jack_port_type(&self) -> &'static str {
         unreachable!()
     }
 
+    /// Panics on call since the `Unowned` spec can't be used to create ports.
     fn jack_flags(&self) -> PortFlags {
         unreachable!()
     }
 
+    /// Panics on call since the `Unowned` spec can't be used to create ports.
     fn jack_buffer_size(&self) -> libc::c_ulong {
         unreachable!()
     }

src/test/test_port.rs

@@ -136,3 +136,21 @@ fn port_can_unset_alias() {
     p.unset_alias("first_alias").unwrap();
     assert_eq!(p.aliases(), vec!["second_alias".to_string()]);
 }
+
+#[test]
+#[should_panic]
+fn port_unowned_no_port_type() {
+    Unowned::default().jack_port_type();
+}
+
+#[test]
+#[should_panic]
+fn port_unowned_no_port_flags() {
+    Unowned::default().jack_flags();
+}
+
+#[test]
+#[should_panic]
+fn port_unowned_no_port_size() {
+    Unowned::default().jack_buffer_size();
+}