Add documentation.

Author: m-ou-se

src/lib.rs

@@ -1,3 +1,91 @@
+//! # PX4 bindings for Rust
+//!
+//! This crate provides the framework to make dynamically loadable PX4 modules
+//! in Rust. Right now, it provides bindings for the two most important APIs:
+//! Logging and uORB. It also provides the entry point for your module, and
+//! handles panics on the main thread of the module.
+//!
+//! ## Compiling and running
+//!
+//! To build a PX4 module in Rust, create a crate as you would for any other
+//! application binary, and then add the following to your Cargo.toml:
+//!
+//! ```text
+//! [lib]
+//! crate-type = ["cdylib"]
+//! path = "src/main.rs"
+//! ```
+//!
+//! This will turn your program into a loadable module instead of a standalone
+//! application. The resulting file will be called `lib<name>.so`, which you
+//! can manually rename to `<name>.px4mod` if you want.
+//!
+//! To run your module, use the
+//! [`dyn`](https://dev.px4.io/en/middleware/modules_command.html#dyn)
+//! PX4 command. Give it the full path name, followed by any arguments to your
+//! module. Note that `dyn` will *not* reload your file if you run it again.
+//! If you want to run a changed version of your module, you'll either need to
+//! restart PX4, or move/rename the file.
+//!
+//! ## Entry point
+//!
+//! Mark your entry function with `#[px4_module_main]`. The boilerplate code
+//! needed to set up the environment and export the function under the right
+//! name is then inserted automatically.
+//!
+//! Your main function should take a `&[&str]` as argument, and return a `i32`
+//! status code. A panic from your main thread is caught and results in a
+//! status code of −1.
+//!
+//! ### Example
+//!
+//! ```
+//! extern crate px4;
+//!
+//! use px4::px4_module_main;
+//!
+//! #[px4_module_main]
+//! fn my_module(args: &[&str]) -> i32 {
+//!   0
+//! }
+//! ```
+//!
+//! ## Logging
+//!
+//! As soon as your main function is entered, logging is already set up using
+//! the standard [`log` crate](https://docs.rs/log/). You can use the standard
+//! logging macros such as `info!`, `warn!`, and `error!` to log messages,
+//! equivalent to `PX4_INFO` (etc.) in C and C++.
+//!
+//! Use the `info_raw!` macro to send raw output, equivalent to the
+//! `PX4_INFO_RAW` macro in C and C++.
+//! Do not use standard output or standard error for this, as the standard
+//! streams of the PX4 process are often not the ones connected to the terminal
+//! the user is looking at.
+//!
+//! ### Example
+//!
+//! ```
+//! extern crate log;
+//! extern crate px4;
+//!
+//! use log::{info, warn};
+//! use px4::px4_module_main;
+//!
+//! #[px4_module_main]
+//! fn my_module(args: &[&str]) -> i32 {
+//!   info!("Hello World!");
+//!   warn!("A warning!");
+//!   panic!("Bye!");
+//! }
+//! ```
+//!
+//! ### uORB
+//!
+//! See the [`uorb` module](uorb/index.html) for documentation on how to use
+//! the uORB bindings.
+//!
+
 extern crate log;
 extern crate px4_macros;
 

src/logging.rs

@@ -6,6 +6,7 @@ extern "C" {
 	fn px4_log_raw(level: i32, fmt: *const u8, ...);
 }
 
+#[doc(hidden)]
 pub enum LogLevel {
 	Debug = 0,
 	Info = 1,
@@ -14,6 +15,7 @@ pub enum LogLevel {
 	Panic = 4,
 }
 
+#[doc(hidden)]
 pub fn log_raw(level: LogLevel, message: &str) {
 	unsafe {
 		px4_log_raw(
@@ -25,6 +27,19 @@ pub fn log_raw(level: LogLevel, message: &str) {
 	}
 }
 
+/// Print output without any decoration.
+///
+/// The equivalent of `PX4_INFO_RAW` in C and C++.
+///
+/// ## Example
+///
+/// ```
+/// # #[macro_use] extern crate px4;
+/// # #[no_mangle] fn px4_log_raw() {}
+/// # fn main() {
+/// info_raw!("Hello {}!\n", "World");
+/// # }
+/// ```
 #[macro_export]
 macro_rules! info_raw {
 	($($arg:tt)+) => (

src/uorb/mod.rs

@@ -1,3 +1,7 @@
+//! Bindings to the uORB messaging system.
+//!
+//! This part is not yet finished.
+
 mod c;
 mod publish;
 mod subscribe;